# Executar consultas SQL no Amazon Athena É possível executar consultas SQL usando origens de dados no Amazon Athena registradas com o AWS Glue Data Catalog e origens de dados, como metastores do Hive e instâncias do Amazon DocumentDB, às quais você se conecta pelo recurso de consulta federada do Athena. Para obter mais informações sobre como trabalhar com fontes de dados, consulte [Conectar-se à fonte de dados](work-with-data-stores.md). Quando você executa uma consulta Data Definition Language (DDL – Linguagem de definição de dados) que modifica o esquema, o Athena grava os metadados no metastore associado à origem dos dados. Algumas consultas, como `CREATE TABLE AS` e `INSERT INTO`, também podem gravar registros no conjunto de dados, por exemplo, adicionando um registro CSV a um local do Amazon S3. Esta seção apresenta orientações para executar consultas do Athena em origens e tipos de dados comuns usando uma variedade de instruções SQL. Há também orientações gerais de como trabalhar com estruturas e operadores comuns, por exemplo, arrays, concatenação, filtragem, nivelamento e classificação. Outros exemplos incluem consultas de dados em tabelas com estruturas aninhadas e mapas, tabelas baseadas em conjuntos de dados codificados com JSON e conjuntos de dados associados aos Serviços da AWS, como logs do AWS CloudTrail e do Amazon EMR. A cobertura completa do uso do SQL padrão está fora do escopo desta documentação. Para obter mais informações sobre SQL, consulte as referências das linguagens [Trino](https://trino.io/docs/current/language.html) e [Presto](https://prestodb.io/docs/current/sql.html). **Topics** + [Visualização de planos de consultas](query-plans.md) + [Trabalhar com resultados de consultas e consultas recentes](querying.md) + [Reutilização de resultados da consulta no Athena](reusing-query-results.md) + [Visualizar estatísticas de consultas](query-stats.md) + [Trabalhar com visualizações](views.md) + [Usar consultas salvas](saved-queries.md) + [Usar consultas parametrizadas](querying-with-prepared-statements.md) + [Usar o otimizador baseado em custos](cost-based-optimizer.md) + [Consultar S3 Express One Zone](querying-express-one-zone.md) + [Consultar o Amazon Glacier](querying-glacier.md) + [Lidar com atualizações de esquemas](handling-schema-updates-chapter.md) + [Consultar matrizes](querying-arrays.md) + [Consultar dados geoespaciais](querying-geospatial-data.md) + [Consultar dados JSON](querying-JSON.md) + [Usar ML com o Athena](querying-mlmodel.md) + [Consultar com UDFs](querying-udf.md) + [Consulta entre regiões](querying-across-regions.md) + [Consultar o AWS Glue Data Catalog](querying-glue-catalog.md) + [Consultar logs do AWS service (Serviço da AWS)](querying-aws-service-logs.md) + [Consultar logs do servidor Web](querying-web-server-logs.md) Para ver as considerações e as limitações, consulte [Considerações e limitações das consultas SQL no Amazon Athena](other-notable-limitations.md). # Visualização de planos de execução para consultas SQL É possível utilizar o editor de consultas do Athena para ver representações gráficas de como uma consulta será executada. Quando você insere uma consulta no editor e escolhe a opção **Explain** (Explicar), o Athena usa uma Instrução SQL [EXPLICAM](athena-explain-statement.md) nessa consulta para criar dois gráficos correspondentes: um plano de execução distribuído e um plano de execução lógico. Esses gráficos podem ser utilizados para analisar, solucionar problemas e melhorar a eficiência das suas consultas. **Para visualizar planos de execução de uma consulta** 1. Insira sua consulta no editor de consultas do Athena e escolha **Explain** (Explicar). ![\[Escolha Explain (Explicar) no editor de consultas do Athena.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/query-plans-1.png) A guia **Distributed plan** (Plano distribuído) mostra o plano de execução da consulta em um ambiente distribuído. Um plano distribuído tem fragmentos ou *estágios* de processamento. Cada estágio tem um número de índice baseado em zero e é processado por um ou mais nós. Dados podem ser trocados entre nós. ![\[Exemplo de gráfico de plano distribuído de consulta.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/query-plans-2.png) 1. Para navegar pelo gráfico, utilize as seguintes opções: + Para aumentar ou diminuir o zoom, role com o mouse ou use os ícones de ampliação. + Para ajustar o gráfico para que ele caiba na tela, selecione o ícone **Zoom to fit** (Ampliar para caber). + Para mover o gráfico, arraste o ponteiro do mouse. 1. Para ver detalhes de um estágio, escolha o estágio. ![\[Escolha um estágio para ver seus detalhes.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/query-plans-3.png) 1. Para ver os detalhes do estágio em largura natural, selecione o ícone de expansão na parte superior direita do painel de detalhes. 1. Para ver mais detalhes, expanda um ou mais itens na árvore do operador. Para obter informações sobre fragmentos de planos distribuídos, consulte [Tipos de saída da instrução EXPLAIN](athena-explain-statement-understanding.md#athena-explain-statement-understanding-explain-plan-types). ![\[Árvore do operador expandida para um estágio em um plano de consulta distribuído.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/query-plans-4.png) **Importante** Alguns filtros de partição podem não estar visíveis no gráfico de árvore do operador aninhado, mesmo que o Athena os aplique à sua consulta. Para verificar o efeito desses filtros, execute [EXPLAIN](athena-explain-statement.md#athena-explain-statement-syntax-athena-engine-version-2) ou [EXPLAIN ANALYZE](athena-explain-statement.md#athena-explain-analyze-statement) na sua consulta e visualize os resultados. 1. Escolha a guia **Logical plan** (Plano lógico). O gráfico mostra o plano lógico para executar a consulta. Para obter mais informações termos operacionais, consulte [Noções básicas dos resultados da instrução EXPLAIN do Athena](athena-explain-statement-understanding.md). ![\[Gráfico de um plano lógico de consulta no Athena.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/query-plans-5.png) 1. Para exportar um plano como uma imagem SVG ou PNG, ou como texto JSON, escolha **Export** (Exportar). ## Recursos adicionais Para obter mais informações, consulte os recursos a seguir. [Usar EXPLAIN e EXPLAIN ANALYZE no Athena](athena-explain-statement.md) [Noções básicas dos resultados da instrução EXPLAIN do Athena](athena-explain-statement-understanding.md) [Visualizar estatísticas e detalhes de execução para consultas concluídas](query-stats.md) [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/7JUyTqglmNU/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/7JUyTqglmNU) # Trabalhar com resultados de consultas e consultas recentes O Amazon Athena armazena automaticamente os resultados das consultas e os metadados dos resultados de cada consulta executada em um *local de resultados de consultas* que você pode especificar no Amazon S3. Se necessário, você pode acessar os arquivos nesse local para trabalhar com eles. Também é possível baixar os arquivos de resultados das consultas diretamente do console do Athena. O Athena agora oferece duas opções para gerenciar os resultados de consultas: você pode usar um bucket S3 de propriedade do cliente ou optar pelo recurso de resultados de consultas gerenciadas. Com seu próprio bucket, você mantém controle total sobre o armazenamento, as permissões, as políticas de ciclo de vida e a retenção, oferecendo máxima flexibilidade, mas exigindo mais gerenciamento. Alternativamente, quando você escolhe a opção de resultados de consultas gerenciadas, o serviço gerencia automaticamente o armazenamento e o ciclo de vida, eliminando a necessidade de configurar um bucket de resultados separado e limpando automaticamente os resultados após um período de retenção predeterminado. Para obter mais informações, consulte [Resultados de consultas gerenciadas](managed-results.md). Para configurar um local de resultados de consultas do Amazon S3 pela primeira vez, veja [Especificar um local para resultados de consultas com uso do console do Athena](query-results-specify-location-console.md). Os arquivos de saída são salvos automaticamente para cada consulta executada. Para acessar e visualizar arquivos de saída de consultas usando o console do Athena, as entidades principais do IAM (usuários e funções) precisam de permissão para a ação [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) do Amazon S3 no local de resultados de consultas, além da permissão para a ação [GetQueryResults](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetQueryResults.html) do Athena. O local de resultados da consulta pode ser criptografado. Se o local estiver criptografado, os usuários deverão ter as permissões de chave apropriadas para criptografar e descriptografar o local de resultados da consulta. **Importante** Os principais do IAM com permissão para a ação `GetObject` do Amazon S3 no local de resultados de consultas podem recuperar os resultados das consultas do Amazon S3 mesmo que a permissão para a ação `GetQueryResults` do Athena seja negada. **nota** No caso de consultas canceladas ou com falha, o Athena pode já ter gravado resultados parciais no Amazon S3. Nesses casos, o Athena não excluirá os resultados parciais do prefixo do Amazon S3 em que os resultados são armazenados. Você deve remover o prefixo do Amazon S3 com os resultados parciais. O Athena usa carregamentos fracionados do Amazon S3 para gravar dados do Amazon S3. Recomendamos que você defina a política de ciclo de vida do bucket para encerrar os carregamentos fracionados nos casos em que as consultas falharem. Para obter mais informações, consulte [Interromper um multipart upload incompleto usando uma política de ciclo de vida de bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html#mpu-abort-incomplete-mpu-lifecycle-config) no *Guia do usuário do Amazon Simple Storage Service*. Em certas condições, o Athena pode repetir automaticamente as execuções de consultas. Na maioria dos casos, essas consultas podem ser concluídas com êxito e o ID da consulta é marcado como `Completed`. É possível que essas consultas tenham gravado resultados parciais durante as primeiras tentativas e que gerem uploads incompletos de várias partes. **Topics** + [Resultados de consultas gerenciadas](managed-results.md) + [Especificar um local para resultados de consultas](query-results-specify-location.md) + [Baixar arquivos de resultados de consultas via console do Athena](saving-query-results.md) + [Visualizar consultas recentes no console do Athena](queries-viewing-history.md) + [Baixar consultas recentes para um arquivo CSV](queries-downloading-multiple-recent-queries-to-csv.md) + [Configurar opções de exibição de consultas recentes](queries-recent-queries-configuring-options.md) + [Manter seu histórico de consultas por mais de 45 dias](querying-keeping-query-history.md) + [Localizar arquivos de saída de consultas no Amazon S3](querying-finding-output-files.md) # Resultados de consultas gerenciadas Com os resultados de consultas gerenciadas, você pode executar consultas SQL sem fornecer um bucket do Amazon S3 para armazenamento de resultados de consultas. Isso evita que você precise provisionar, gerenciar, controlar o acesso e limpar seus próprios buckets do S3. Para começar, crie um novo grupo de trabalho ou edite um grupo de trabalho existente. Em **Query result configuration**, selecione **Athena managed**. **Atributos principais** + Simplifica seu fluxo de trabalho removendo a necessidade de escolher um local de bucket do S3 antes de executar as consultas. + Sem custos adicionais para usar resultados de consultas gerenciadas e com a exclusão automática dos resultados da consulta, a sobrecarga administrativa e a necessidade de processos separados de limpeza de buckets do S3 são reduzidas. + Fácil de começar: grupos de trabalho novos e preexistentes podem ser facilmente configurados para usar resultados de consultas gerenciadas. Você pode ter uma combinação de resultados de consultas gerenciadas pelo Athena e gerenciados pelo cliente em sua conta da AWS. + Permissões simplificadas do IAM com acesso aos resultados de leitura através de `GetQueryResults` e `GetQueryResultsStream` vinculados a grupos de trabalho individuais. + Os resultados da consulta são criptografados automaticamente com sua escolha de chaves de propriedade da AWS ou chaves de propriedade do cliente. ## Considerações e limitações **** + O acesso aos resultados da consulta é gerenciado no nível do grupo de trabalho no Athena. Para isso, você precisa de permissões explícitas para ações `GetQueryResults` e `GetQueryResultsStream` do IAM no grupo de trabalho específico. A ação `GetQueryResults` determina quem pode recuperar os resultados de uma consulta concluída em um formato paginado, enquanto a ação `GetQueryResultsStream` determina quem pode transmitir os resultados de uma consulta concluída (comumente usada pelos drivers do Athena). + Você não pode baixar arquivos de resultados de consultas maiores que 200 MB do console. Use a instrução `UNLOAD` para gravar resultados maiores que 200 MB em um local para o qual você possa baixar separadamente. + O atributo de resultados de consultas gerenciadas não oferece suporte à [reutilização dos resultados da consulta](reusing-query-results.md). + Os resultados da consulta ficam disponíveis por 24 horas. Os resultados da consulta são armazenados sem nenhum custo para você durante esse período. Após esse período, os resultados da consulta são excluídos automaticamente. ## Criar ou editar um grupo de trabalho com resultados de consultas gerenciadas Para criar um grupo de trabalho ou atualizar um grupo de trabalho existente com resultados de consultas gerenciadas no console: 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/). 1. No menu à esquerda, escolha **Workgroups**. 1. Escolha **Create Workgroup** para criar um novo grupo de trabalho ou editar um grupo de trabalho existente na lista. 1. Em **Query result configuration**, escolha **Athena managed**. ![\[O menu Query result configuration.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/athena-managed.png) 1. Em **Encrypt query results**, escolha a opção de criptografia desejada. Para obter mais informações, consulte [Escolha a criptografia do resultado da consulta](#managed-query-results-encryption-at-rest). 1. Preencha todos os outros detalhes necessários e escolha **Save changes**. ## Escolha a criptografia do resultado da consulta Há duas opções para essa configuração de criptografia: + **Criptografar usando uma chave da AWS própria**: esta é a opção padrão quando você usa resultados de consultas gerenciadas. Escolha essa opção se quiser que os resultados da consulta sejam criptografados por uma chave própria da AWS. + **Criptografar usando a chave gerenciada pelo cliente**: escolha esta opção se quiser criptografar e descriptografar os resultados da consulta com uma chave gerenciada pelo cliente. Para usar uma chave gerenciada pelo cliente, adicione o serviço Athena no elemento da entidade principal da seção de política de chaves. Para obter mais informações, consulte [Configurar uma política de chave do AWS KMS para resultados de consultas gerenciadas](#managed-query-results-set-up). Para executar consultas com sucesso, o usuário que executa as consultas precisa de permissão para acessar a chave do AWS KMS. ## Configurar uma política de chave do AWS KMS para resultados de consultas gerenciadas A seção `Principal` na política de chaves especifica quem pode usar essa chave. O atributo de resultados de consultas gerenciadas apresenta a entidade principal `encryption.athena.amazonaws.com` que você deve especificar na seção `Principal`. Essa entidade principal de serviço serve especificamente para acessar chaves que não são de propriedade do Athena. Você também deve adicionar as ações `kms:Decrypt`, `kms:GenerateDataKey` e `kms:DescribeKey` à política de chave que você usa para acessar os resultados gerenciados. Essas três ações são as ações mínimas permitidas. Os resultados de consultas gerenciadas usam o ARN do seu grupo de trabalho para o [contexto de criptografia](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context). Como a seção `Principal` é um serviço da AWS, você também precisa adicionar `aws:sourceArn` e `aws:sourceAccount` as condições da política de chave. O exemplo a seguir mostra uma política de chave do AWS KMS que tem permissões mínimas em um único grupo de trabalho. ``` { "Sid": "Allow athena service principal to use the key", "Effect": "Allow", "Principal": { "Service": "encryption.athena.amazonaws.com" }, "Action": [ "kms:Decrypt", "kms:GenerateDataKey", "kms:DescribeKey" ], "Resource": "arn:aws:kms:us-east-1:{account-id}:key/{key-id}", "Condition": { "ArnLike": { "kms:EncryptionContext:aws:athena:arn": "arn:aws:athena:us-east-1:{account-id}:workgroup/{workgroup-name}", "aws:SourceArn": "arn:aws:athena:us-east-1:{account-id}:workgroup/{workgroup-name}" }, "StringEquals": { "aws:SourceAccount": "{account-id}" } } ``` O exemplo de política de chave do AWS KMS a seguir permite que todos os grupos de trabalho dentro da mesma *account-id* usem a mesma chave do AWS KMS. ``` { "Sid": "Allow athena service principal to use the key", "Effect": "Allow", "Principal": { "Service": "encryption.athena.amazonaws.com" }, "Action": [ "kms:Decrypt", "kms:GenerateDataKey", "kms:DescribeKey" ], "Resource": "arn:aws:kms:us-east-1:account-id:key/{key-id}", "Condition": { "ArnLike": { "kms:EncryptionContext:aws:athena:arn": "arn:aws:athena:us-east-1:account-id:workgroup/*", "aws:SourceArn": "arn:aws:athena:us-east-1:account-id:workgroup/*" }, "StringEquals": { "aws:SourceAccount": "account-id" } } } ``` Além das permissões do Athena e do Amazon S3, você também deve obter permissões para realizar ações `kms:GenerateDataKey` e `kms:Decrypt`. Para obter mais informações, consulte [Permissões para dados criptografados no Amazon S3](encryption.md#permissions-for-encrypting-and-decrypting-data). Para obter mais informações sobre a criptografia de resultados de consultas gerenciadas, consulte [Criptografar resultados de consultas gerenciadas](encrypting-managed-results.md). # Criptografar resultados de consultas gerenciadas O Athena oferece as seguintes opções para criptografar os [Resultados de consultas gerenciadas](managed-results.md). ## Criptografar usando uma chave de propriedade da AWS Essa é a opção padrão quando você usa os resultados de consultas gerenciadas. Essa opção indica que você deseja criptografar os resultados de consultas usando uma chave de propriedade da AWS. As chaves de propriedade da AWS não são armazenadas em sua conta AWS e fazem parte de uma coleção de chaves do KMS que a AWS possui. Não é cobrada taxa mensal nem taxa de uso de chaves pertencentes à AWS, e elas não são contabilizadas com base nas cotas do AWS KMS para a sua conta. ## Criptografe usando chaves gerenciadas pelo cliente do AWS KMS Chaves gerenciadas pelo cliente são chaves do KMS disponíveis na sua conta AWS que você cria, detém e gerencia. Você tem controle total sobre essas chaves do KMS, inclusive para estabelecer e manter as políticas de chaves, as políticas do IAM e as concessões; habilitar e desabilitar as chaves do KMS; alternar seu material de criptografia; adicionar tags; criar aliases que fazem referência a elas; e programar a exclusão delas. Para obter mais informações, consulte [Chaves gerenciadas pelo cliente](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk). ## Como o Athena usa a chave gerenciada pelo cliente para criptografar resultados Quando você especifica uma chave gerenciada pelo cliente, o Athena a usa para criptografar os resultados de consultas quando armazenados nos resultados de consultas gerenciadas. A mesma chave é usada para descriptografar os resultados quando você chama o `GetQueryResults`. Quando você define o estado da chave gerenciada pelo cliente como desativada ou a agenda para exclusão, isso impede que o Athena e todos os usuários criptografem ou descriptografem os resultados com essa chave. O Athena usa criptografia envelopada e hierarquia de chaves para criptografar dados. A chave de criptografia do AWS KMS é usada para gerar e descriptografar a chave raiz dessa hierarquia de chaves. Cada resultado é criptografado usando a chave gerenciada pelo cliente configurada no grupo de trabalho no momento da criptografia. Alternar a chave para uma chave diferente gerenciada pelo cliente ou para uma chave de propriedade da AWS não criptografa novamente os resultados existentes com a nova chave. A exclusão e desativação de uma determinada chave gerenciada pelo cliente afeta apenas a descriptografia dos resultados que a chave criptografou. O Athena precisa acessar sua chave de criptografia para realizar operações `kms:Decrypt`, `kms:GenerateDataKey` e `kms:DescribeKey` para criptografar e descriptografar os resultados. Para obter mais informações, consulte [Permissões para dados criptografados no Amazon S3](encryption.md#permissions-for-encrypting-and-decrypting-data). A entidade principal que envia a consulta usando a API `StartQueryExecution` e lê os resultados usando o `GetQueryResults` também deve ter permissão para a chave gerenciada pelo cliente para operações `kms:Decrypt`, `kms:GenerateDataKey` e `kms:DescribeKey`, além das permissões do Athena e do Amazon S3. Para saber mais, consulte [Usar políticas de chaves no AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default-allow-users). # Especificar um local para resultados de consultas O local de resultados de consultas usado pelo Athena é determinado por uma combinação de configurações de grupo de trabalho e *do lado do cliente*. As configurações do lado do cliente são baseadas na forma como você executa a consulta. + Se você executar a consulta usando o console do Athena, o **Query result location** (Local de resultados da consulta) inserido em **Settings** (Configurações) na barra de navegação determinará a configuração do lado do cliente. + Se você executar a consulta usando a API do Athena, o parâmetro `OutputLocation` da ação [StartQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html) determinará a configuração do lado do cliente. + Se você usar os drivers ODBC ou JDBC para executar consultas, a propriedade `S3OutputLocation` especificada no URL de conexão determinará a configuração no lado do cliente. **Importante** Quando você executa uma consulta usando a API ou usando o driver ODBC ou JDBC, a configuração do console não se aplica. Cada configuração de grupo de trabalho tem uma opção [Override client-side settings (Substituir configurações no lado do cliente)](https://docs.aws.amazon.com/athena/latest/ug/workgroups-settings-override.html) que pode ser habilitada. Quando essa opção está habilitada, as configurações do grupo de trabalho têm precedência sobre as configurações aplicáveis do lado do cliente quando uma entidade principal do IAM associada a esse grupo de trabalho executa a consulta. ## Sobre locais padrão já criados Anteriormente no Athena, se você executasse uma consulta sem especificar um valor em **Query result location** (Local de resultados de consultas) e a configuração de local de resultados de consultas não fosse substituída por um grupo de trabalho, o Athena criava um local padrão para você. O local padrão era `aws-athena-query-results-MyAcctID-MyRegion`, em que *MyAcctID* era o ID da conta da Amazon Web Services do principal do IAM que executava a consulta, e *MyRegion* era a região em que a consulta era executada (por exemplo, `us-west-1`). Agora, antes de executar uma consulta do Athena em uma região onde sua conta nunca acessou o Athena, você deve especificar um local de resultados de consultas ou usar um grupo de trabalho que substitua a configuração desse local. O Athena não cria mais um local padrão de resultados de consultas para você, mas os locais padrão `aws-athena-query-results-MyAcctID-MyRegion` que já foram criados permanecem válidos e você pode continuar a usá-los. **Topics** + [Sobre locais padrão já criados](#query-results-specify-location-previous-defaults) + [Especificar um local para resultados de consultas com uso do console do Athena](query-results-specify-location-console.md) + [Especificar um local para resultados de consultas com uso de um grupo de trabalho](query-results-specify-location-workgroup.md) # Especificar um local para resultados de consultas com uso do console do Athena Antes de executar uma consulta, um local de bucket de resultados de consultas do Amazon S3 precisa ser especificado, ou você deve usar um grupo de trabalho que especificou um bucket e com uma configuração que substitui as configurações do cliente. **Para especificar um local de resultados de consultas na configuração do lado do cliente usando o console do Athena** 1. [Alterne](switching-workgroups.md) para o grupo de trabalho para o qual você deseja especificar um local de resultados de consultas. O nome do grupo de trabalho padrão é **primary**. 1. No painel de navegação, escolha **Settings** (Configurações). 1. Na barra de navegação, escolha **Manage** (Gerenciar). 1. Em **Manage settings** (Gerenciar configurações), faça um dos seguintes procedimentos: + Na caixa de texto **Query result location** (Localização dos resultados da consulta), insira o caminho para o bucket criado no Amazon S3 para resultados de consultas. Adicione o prefixo ao caminho `s3://`. + Escolha **Browse S3** (Navegar no S3), escolha o bucket do Amazon S3 que você criou na região atual e escolha **Choose** (Escolher). **nota** Se você estiver usando um grupo de trabalho que especifica um local para os resultados das consultas para todos os usuários do grupo de trabalho, a opção para alterar o local dos resultados das consultas não estará disponível. 1. (Opcional) Escolha **View lifecycle configuration** (Exibir configuração do ciclo de vida) para visualizar e configurar as [regras de ciclo de vida do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) em seu bucket de resultados de consulta. As regras de ciclo de vida do Amazon S3 que você cria podem ser regras de expiração ou regras de transição. As regras de expiração excluem os resultados de consultas automaticamente após determinado tempo. As regras de transição os transferem para outro nível de armazenamento do Amazon S3. Para obter mais informações, consulte [Definir configuração do ciclo de vida em bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-set-lifecycle-configuration-intro.html) no Guia do usuário do Amazon Simple Storage Service. 1. (Opcional) Para **Expected bucket owner** (Proprietário esperado do bucket), insira o ID da Conta da AWS que você espera ser a proprietária do bucket do local de saída. Essa é uma medida de segurança adicional. Se o ID da conta do proprietário do bucket não corresponder ao ID especificado aqui, as tentativas de saída para o bucket falharão. Para obter informações detalhadas, consulte [Verificar propriedade do bucket com a condição de proprietário do bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-owner-condition.html) no *Guia do usuário do Amazon S3*. **nota** A configuração esperada do proprietário do bucket se aplica somente ao local de saída do Amazon S3 que você especificar para os resultados da consulta do Athena. Ela não se aplica a outros locais do Amazon S3, como locais de origem dos dados em buckets externos do Amazon S3, locais da tabela de destino `CTAS` e `INSERT INTO`, locais de saída da instrução `UNLOAD`, operações para buckets de vazamento para consultas federadas ou consultas `SELECT` executadas em uma tabela em outra conta. 1. (Opcional) Escolha **Encrypt query results** (Criptografar resultados da consulta) para criptografar os resultados das consultas que estão armazenados no Amazon S3. Para obter mais informações sobre criptografia no Athena, consulte [Criptografia em repouso](encryption.md). 1. (Opcional) Escolha **Assign bucket owner full control over query results** (Atribuir controle total ao proprietário do bucket sobre os resultados das consultas) para que proprietário do bucket tenha acesso de controle total sobre os resultados das consultas quando [ACLs estiverem habilitadas](https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html) para o bucket de resultados de consultas. Por exemplo, se a localização dos resultados das consultas pertencer a outra conta, será possível conceder propriedade e controle total sobre os resultados das consultas à outra conta. Para obter mais informações, consulte [Controlar a propriedade de objetos e desabilitar ACLs para seu bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html), no *Guia do Usuário do Amazon S3*. 1. Escolha **Salvar**. # Especificar um local para resultados de consultas com uso de um grupo de trabalho Especifique o local de resultados de consultas em uma configuração de grupo de trabalho usando o Console de gerenciamento da AWS, a AWS CLI ou a API do Athena. Ao usar a AWS CLI, especifique a localização do resultado da consulta usando o parâmetro `OutputLocation` da opção `--configuration` ao executar o comando [https://docs.aws.amazon.com/cli/latest/reference/athena/create-work-group.html](https://docs.aws.amazon.com/cli/latest/reference/athena/create-work-group.html) ou [https://docs.aws.amazon.com/cli/latest/reference/athena/update-work-group.html](https://docs.aws.amazon.com/cli/latest/reference/athena/update-work-group.html). **Para especificar o local de resultados de consultas para um grupo de trabalho usando o console do Athena** 1. Se o painel de navegação do console não estiver visível, escolha o menu de expansão à esquerda. ![\[Escolha o menu de expansão.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/nav-pane-expansion.png) 1. No painel de navegação, escolha **Global networks** (Redes globais). 1. Na lista de grupos de trabalho, escolha o link do grupo de trabalho que você deseja editar. 1. Escolha **Editar**. 1. Em **Query result location and encryption** (Local do resultado da consulta e criptografia), siga um destes procedimentos: + Na caixa de texto **Query result location** (Local dos resultados de consultas), insira o caminho para o bucket criado no Amazon S3 para resultados de consultas. Adicione o prefixo ao caminho `s3://`. + Escolha **Browse S3** (Navegar no S3), escolha o bucket do Amazon S3 que você criou na região que desejar usar e escolha **Choose** (Escolher). 1. (Opcional) Para **Expected bucket owner** (Proprietário esperado do bucket), insira o ID da Conta da AWS que você espera ser a proprietária do bucket do local de saída. Essa é uma medida de segurança adicional. Se o ID da conta do proprietário do bucket não corresponder ao ID especificado aqui, as tentativas de saída para o bucket falharão. Para obter informações detalhadas, consulte [Verificar propriedade do bucket com a condição de proprietário do bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-owner-condition.html) no *Guia do usuário do Amazon S3*. **nota** A configuração esperada do proprietário do bucket se aplica somente ao local de saída do Amazon S3 que você especificar para os resultados da consulta do Athena. Ela não se aplica a outros locais do Amazon S3, como locais de origem dos dados em buckets externos do Amazon S3, locais da tabela de destino `CTAS` e `INSERT INTO`, locais de saída da instrução `UNLOAD`, operações para buckets de vazamento para consultas federadas ou consultas `SELECT` executadas em uma tabela em outra conta. 1. (Opcional) Escolha **Encrypt query results** (Criptografar resultados da consulta) para criptografar os resultados das consultas que estão armazenados no Amazon S3. Para obter mais informações sobre criptografia no Athena, consulte [Criptografia em repouso](encryption.md). 1. (Opcional) Escolha **Assign bucket owner full control over query results** (Atribuir controle total ao proprietário do bucket sobre os resultados das consultas) para que proprietário do bucket tenha acesso de controle total sobre os resultados das consultas quando [ACLs estiverem habilitadas](https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html) para o bucket de resultados de consultas. Por exemplo, se a localização dos resultados das consultas pertencer a outra conta, será possível conceder propriedade e controle total sobre os resultados das consultas à outra conta. Se a configuração para S3 Object Ownership (Propriedade de objetos do S3) for **Bucket owner preferred** (Proprietário do bucket preferencial), o proprietário do bucket também possuirá todos os objetos de resultados de consultas gravados a partir deste grupo de trabalho. Por exemplo, quando o grupo de trabalho de uma conta externa habilita essa opção e define a localização dos resultados das consultas como o bucket do Amazon S3 da sua conta, cuja configuração S3 Object Ownership (Propriedade de objetos do S3) é **Bucket owner preferred** (Proprietário do bucket preferencial), você é o proprietário e tem acesso de controle total sobre os resultados da consulta do grupo de trabalho externo. A seleção dessa opção com a configuração configuração S3 Object Ownership (Propriedade de objetos do S3) definida como **Bucket owner enforced** (Proprietário do bucket imposto) não surte efeito. Para obter mais informações, consulte [Controlar a propriedade de objetos e desabilitar ACLs para seu bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html), no *Guia do Usuário do Amazon S3*. 1. Se quiser exigir que todos os usuários do grupo de trabalho usem o local de resultados de consultas especificado, role para baixo até a seção **Settings** (Configurações) e selecione **Override client-side settings** (Substituir configurações no lado do cliente). 1. Escolha **Salvar alterações**. # Baixar arquivos de resultados de consultas via console do Athena É possível baixar o arquivo CSV dos resultados da consulta no painel logo após executar uma consulta. Também é possível baixar os resultados da consulta recente na guia **Recent queries** (Consultas recentes). **nota** Os arquivos de resultados das consultas do Athena são arquivos de dados com informações que podem ser configuradas por usuários específicos. Alguns programas que leem e analisam esses dados podem interpretar alguns deles como comandos (injeção de CSV). Por esse motivo, quando você importa dados CSV de resultados de consultas para um programa de planilha, esse programa pode avisá-lo sobre problemas de segurança. Para manter seu sistema seguro, você deve sempre escolher a opção para desabilitar links ou macros dos resultados de consulta baixados. **Para executar uma consulta e baixar os resultados** 1. Insira sua consulta no editor de consultas e escolha **Run** (Executar). Quando a execução da consulta terminar, o painel **Results (Resultados)** mostrará os resultados da consulta. 1. Para baixar um arquivo CSV dos resultados da consulta, escolha **Download results** (Baixar resultados) acima do painel de resultados de consultas. Dependendo da configuração do navegador e do navegador, pode ser necessário confirmar o download. ![\[Salvar os resultados da consulta em um arquivo .csv no console do Athena.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/getting-started-query-results-download-csv.png) **Como fazer download de um arquivo de resultados de uma consulta anterior** 1. Escolha **Recent queries** (Consultas recentes). ![\[Escolha Recent queries (Consultas recentes) para visualizar consultas anteriores.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/getting-started-recent-queries.png) 1. Use a caixa de pesquisa para localizar a consulta, escolha a consulta e escolha **Download results** (Baixar resultados). **nota** Não é possível usar a opção **Download results** (Baixar resultados) para recuperar resultados de consultas que foram excluídos manualmente ou foram excluídos ou movidos para outro local pelas [regras de ciclo de vida](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-set-lifecycle-configuration-intro.html) do Amazon S3. ![\[Escolha Recent queries (Consultas recentes). para localizar e baixar resultados de consultas anteriores.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-recent-queries-tab-download.png) # Visualizar consultas recentes no console do Athena Você pode usar o console do Athena para ver quais consultas foram bem-sucedidas ou falharam, e visualizar os detalhes dos erros para as consultas que falharam. O Athena mantém o histórico de consultas por 45 dias. **Para visualizar consultas recentes no console do Athena** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. Escolha **Recent queries** (Consultas recentes). A guia **Recent queries** (Consultas recentes) mostra informações sobre cada consulta executada. 1. Para abrir uma instrução de consulta no editor de consultas, escolha o ID de execução da consulta. ![\[Escolha o ID de execução de uma consulta para vê-la no editor de consultas.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-view-query-statement.png) 1. Para ver os detalhes de uma consulta que não foi bem-sucedida, escolha o link **Failed** (Com falha) para a consulta. ![\[Selecione o link Failed (Com falha) Link para uma consulta para visualizar informações sobre a falha.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-view-query-failure-details.png) # Baixar consultas recentes para um arquivo CSV É possível usar a guia **Recent queries** (Consultas recentes) do console do Athena para exportar uma ou mais consultas recentes para um arquivo CSV com a finalidade de visualizá-las em formato tabular. O arquivo baixado não contém os resultados da consulta, mas a própria string de consulta SQL e outras informações sobre a consulta. Os campos exportados incluem o ID de execução, o conteúdo da string de consulta, o horário de início da consulta, o status, o tempo de execução, a quantidade de dados verificados, a versão usada do mecanismo de consulta e o método de criptografia. É possível exportar, no máximo, 500 consultas recentes ou, no máximo, 500 consultas filtradas usando critérios inseridos na caixa de pesquisa. **Para exportar uma ou mais consultas recentes para um arquivo CSV** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. Escolha **Recent queries** (Consultas recentes). 1. (Opcional) Use a caixa de pesquisa para filtrar as consultas recentes que você deseja baixar 1. Escolha **Fazer download do CSV**. ![\[Escolha Fazer download do CSV.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-recent-queries-csv.png) 1. Na solicitação de salvamento do arquivo, escolha **Save** (Salvar). O nome de arquivo padrão é `Recent Queries` seguido por um carimbo de data/hora (por exemplo, `Recent Queries 2022-12-05T16 04 27.352-08 00.csv`). # Configurar opções de exibição de consultas recentes É possível configurar opções para a guia **Recent queries** (Consultas recentes), como colunas a serem exibidas e quebra de texto. **Para configurar as opções da guia **Recent queries** (Consultas recentes)** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. Escolha **Recent queries** (Consultas recentes). 1. Escolha o botão de opções (ícone de engrenagem). ![\[Escolha o botão de opção para configurar a exibição de consultas recentes.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-recent-queries-options.png) 1. Na caixa de diálogo **Preferences** (Preferências), escolha o número de linhas por página, o comportamento de quebra de linha e as colunas a serem exibidas. ![\[Configurar a exibição de consultas recentes.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-recent-queries-preferences.png) 1. Selecione a opção **Confirmar**. # Manter seu histórico de consultas por mais de 45 dias Se você deseja manter o histórico de consultas por mais de 45 dias, é possível recuperá-lo e salvá-lo em um armazenamento de dados, como o Amazon S3. Para automatizar esse processo, é possível usar as ações da API do Athena e do Amazon S3 e os comandos da CLI. O procedimento a seguir resume essas etapas. **Como recuperar e salvar o histórico de consultas programaticamente** 1. Use a ação da API [ListQueryExecutions](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListQueryExecutions.html) do Athena ou o comando da CLI [list-query-executions](https://docs.aws.amazon.com/cli/latest/reference/athena/list-query-executions.html) para recuperar os IDs das consultas. 1. Use a ação da API [GetQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetQueryExecution.html) do Athena ou o comando da CLI [get-query-execution](https://docs.aws.amazon.com/cli/latest/reference/athena/get-query-execution.html) para recuperar as informações sobre cada consulta com base no ID. 1. Use a ação da API [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) do Amazon S3 ou o comando da CLI [put-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html) para salvar as informações no Amazon S3. # Localizar arquivos de saída de consultas no Amazon S3 Os arquivos de saída das consultas são armazenados em subpastas no Amazon S3 no padrão de caminho a seguir, a menos que a consulta seja feita em um grupo de trabalho com uma configuração que substitua as configurações no lado do cliente. Quando a configuração do grupo de trabalho substitui as configurações no lado do cliente, a consulta usa o caminho de resultados especificado pelo grupo de trabalho. ``` QueryResultsLocationInS3/[QueryName|Unsaved/yyyy/mm/dd/] ``` + *QueryResultsLocationInS3* é o local de resultados da consulta especificado pelas configurações do grupo de trabalho ou pelo lado do cliente. Para obter mais informações, consulte [Especificar um local para resultados de consultas](query-results-specify-location.md) adiante neste documento. + As seguintes subpastas são criadas somente para consultas executadas no console cujo caminho de resultados ainda não foi substituído pela configuração do grupo de trabalho. As consultas executadas pela AWS CLI ou usando a API do Athena são salvas diretamente em *QueryResultsLocationInS3*. + *Queryname* é o nome da consulta para a qual os resultados são salvos. Se a consulta foi executada, mas não salva, `Unsaved` será usado. + *aaaa/mm/dd* é a data em que a consulta foi executada. Os arquivos associados a uma consulta `CREATE TABLE AS SELECT` são armazenados em uma subpasta `tables` do padrão acima. ## Identificar arquivos de saída de consultas Os arquivos são salvos no local de resultados de consultas no Amazon S3 com base no nome, no ID e na data de execução da consulta. Os arquivos de cada consulta são nomeados usando *QueryID*, que é um identificador exclusivo que o Athena atribui a cada consulta quando ela é executada. Os seguintes tipos de arquivo são salvos: | Tipo de arquivo | Padrão de nomenclatura de arquivos | Descrição | | --- | --- | --- | | **Arquivos de resultados da consulta** | `QueryID.csv` `QueryID.txt` | Os arquivos de resultados da consulta DML são salvos no formato CSV (valores separados por vírgulas). Os resultados da consulta DDL são salvos como arquivos de texto sem formatação. Você pode baixar os arquivos de resultados do console do painel **Results** (Resultados) ao usar o console ou do **History** (Histórico) da consulta. Para obter mais informações, consulte [Baixar arquivos de resultados de consultas via console do Athena](saving-query-results.md). | | **Arquivos de metadados da consulta** | `QueryID.csv.metadata` `QueryID.txt.metadata` | Os arquivos de metadados de consulta DML e DDL são salvos no formato binário e não são legíveis por humanos. A extensão do arquivo corresponde ao arquivo relacionado de resultados de consultas. O Athena usa os metadados ao ler os resultados da consulta usando a ação `GetQueryResults`. Embora esses arquivos possam ser excluídos, não recomendamos porque informações importantes sobre a consulta são perdidas. | | **Arquivos manifesto de dados** | `QueryID-manifest.csv` | Os arquivos manifesto de dados são gerados para monitorar os arquivos que o Athena cria em locais de origens de dados do Amazon S3 quando uma consulta [INSERT INTO](insert-into.md) é executada. Se uma consulta falhar, o manifesto também rastreará os arquivos que a consulta pretendia gravar. O manifesto é útil para identificar arquivos órfãos resultantes de uma consulta com falha. | ## Usar o AWS CLI para identificar o local e dos arquivos de saída de consultas Para usar a AWS CLI para identificar o local de saída e os arquivos de resultados das consultas, execute o comando `aws athena get-query-execution` conforme o exemplo a seguir. Substitua *abc1234d-5efg-67hi-jklm-89n0op12qr34* pelo ID da consulta. ``` aws athena get-query-execution --query-execution-id abc1234d-5efg-67hi-jklm-89n0op12qr34 ``` Esse comando retorna uma saída semelhante à seguinte. Para ver as descrições de cada parâmetro de saída, consulte [get-query-execution](https://docs.aws.amazon.com/cli/latest/reference/athena/get-query-execution.html) na *Referência de comandos da AWS CLI*. ``` { "QueryExecution": { "Status": { "SubmissionDateTime": 1565649050.175, "State": "SUCCEEDED", "CompletionDateTime": 1565649056.6229999 }, "Statistics": { "DataScannedInBytes": 5944497, "DataManifestLocation": "s3://amzn-s3-demo-bucket/athena-query-results-123456789012-us-west-1/MyInsertQuery/2019/08/12/abc1234d-5efg-67hi-jklm-89n0op12qr34-manifest.csv", "EngineExecutionTimeInMillis": 5209 }, "ResultConfiguration": { "EncryptionConfiguration": { "EncryptionOption": "SSE_S3" }, "OutputLocation": "s3://amzn-s3-demo-bucket/athena-query-results-123456789012-us-west-1/MyInsertQuery/2019/08/12/abc1234d-5efg-67hi-jklm-89n0op12qr34" }, "QueryExecutionId": "abc1234d-5efg-67hi-jklm-89n0op12qr34", "QueryExecutionContext": {}, "Query": "INSERT INTO mydb.elb_log_backup SELECT * FROM mydb.elb_logs LIMIT 100", "StatementType": "DML", "WorkGroup": "primary" } } ``` # Reutilização de resultados da consulta no Athena Ao executar novamente uma consulta no Athena, é possível optar por reutilizar o último resultado de consulta armazenado, se desejar. Essa opção pode aumentar a performance e reduzir os custos, em termos de números, para os bytes verificados. A reutilização dos resultados da consulta é útil se, por exemplo, você souber que os resultados não serão alterados em um determinado período de tempo. É possível especificar um período máximo para a reutilização dos resultados da consulta. O Athena usará o resultado armazenado desde que não seja mais antigo do que o período especificado. Para obter mais informações, consulte [Reduzir custo e melhorar o desempenho de consultas com Amazon Athena](https://aws.amazon.com/blogs/big-data/reduce-cost-and-improve-query-performance-with-amazon-athena-query-result-reuse/) no *Blog de Big Data da AWS*. ## Atributos principais Ao habilitar a reutilização de resultados para uma consulta, o Athena irá procurar uma execução anterior da consulta no mesmo grupo de trabalho. Se o Athena encontrar uma correspondência, ela ignorará a execução e retornará o resultado da consulta da execução anterior correspondente. É possível habilitar a reutilização dos resultados da consulta por consulta. O Athena reutilizará o resultado da última consulta quando todas as seguintes condições forem verdadeiras: + As strings de consulta correspondem conforme determinado por Athena. + Os nomes do banco de dados e do catálogo correspondem. + O resultado anterior não expirou. + A configuração do resultado da consulta corresponde à configuração do resultado da consulta da execução anterior. + Você tem acesso a todas as tabelas referenciadas na consulta. + Você tem acesso ao local do arquivo S3 no qual o resultado anterior está armazenado. Se alguma dessas condições não for atendida, o Athena executará a consulta sem usar os resultados armazenados em cache. ## Considerações e limitações Ao usar o recurso de reutilização dos resultados da consulta, lembre-se dos seguintes pontos: + O Athena reutiliza os resultados da consulta somente dentro do mesmo grupo de trabalho. + O recurso de reutilização dos resultados da consulta respeita as configurações do grupo de trabalho. Se você substituir a configuração de resultado de uma consulta, o recurso será desativado. + Somente consultas que produzem conjuntos de resultados no Amazon S3 são compatíveis. As instruções que não sejam `SELECT` e `EXECUTE` não são compatíveis. + Tabelas do Apache Hive, Apache Hudi, Apache Iceberg e Linux Foundation Delta Lake registradas com AWS Glue são suportados. Metastores do Hive externos não são compatíveis. + Não há suporte para as consultas que fazem referência a catálogos federados ou a um metastore Hive externo. + Não há suporte para a reutilização dos resultados da consulta para tabelas governadas do Lake Formation. + A reutilização do resultado da consulta não é compatível quando o local da origem da tabela no Amazon S3 é registrado como um local de dados no Lake Formation. + Não há suporte para tabelas com permissões de linha e de coluna. + Tabelas com controle de acesso refinado (por exemplo, filtragem de colunas ou linhas) não são compatíveis. + Qualquer consulta que referencie uma tabela não compatível não está qualificada para reutilizar os resultados da consulta. + O Athena requer que você tenha permissões de leitura do Amazon S3 para que o arquivo de saída gerado anteriormente seja reutilizado. + O recurso de reutilização dos resultados da consulta assume que o conteúdo do resultado anterior não foi modificado. O Athena não verifica a integridade de um resultado anterior antes de usá-lo. + Se os resultados da consulta da execução anterior foram excluídos ou movidos para um local diferente no Amazon S3, a execução subsequente da mesma consulta não reutilizará os resultados da consulta anterior. + Há a possibilidade de que resultados potencialmente obsoletos retornem. O Athena não verifica alterações nos dados de origem até que o período máximo de reutilização especificado seja atingido. + Se diversos resultados estiverem disponíveis para reutilização, o Athena usará o resultado mais recente. + Consultas que usam operadores ou funções não determinísticas como `rand()` ou `shuffle()` não usam resultados em cache. Por exemplo, `LIMIT` sem `ORDER BY` não é determinístico e não está armazenado em cache, mas `LIMIT` com `ORDER BY` é determinístico e está armazenado em cache. + Para usar o recurso de reutilização de resultados de consulta com o JDBC, a versão mínima necessária do driver é 2.0.34.1000. Para ODBC, a versão mínima necessária do driver é 1.1.19.1002. Para obter informações sobre download de drivers, consulte [Conectar ao Amazon Athena com drivers JDBC e ODBC](athena-bi-tools-jdbc-odbc.md). + Não há compatibilidade para reutilizar os resultados da consulta em consultas que usem mais de um catálogo de dados. + Não há compatibilidade para reutilizar os resultados da consulta em consultas que incluam mais de 20 tabelas. + Para strings de consulta com menos de 100 KB, as diferenças nos comentários e no espaço em branco são ignoradas, e `INNER JOIN` e `JOIN` são tratados como equivalentes para fins de reutilização dos resultados. As strings de consulta maiores que 100 KB devem ser uma correspondência exata para reutilizar os resultados. + Um resultado de consulta será considerado expirado se for mais antigo que o período máximo especificado, ou mais antigo que o padrão de 60 minutos se um período máximo não tiver sido especificado. O período máximo para a reutilização dos resultados da consulta pode ser especificada em minutos, horas ou dias. O período máximo especificado é equivalente a sete dias, independentemente da unidade de tempo usada. + Os [resultados de consultas gerenciadas](https://docs.aws.amazon.com/athena/latest/ug/managed-results.html) não é compatível. ## Como reutilizar os resultados da consulta no console do Athena Para usar o recurso, habilite a opção **Reuse query results** (Reutilizar resultados da consulta) no editor de consultas do Athena. ![\[Habilite Reuse query results (Reutilizar resultados da consulta) no editor de consultas do Athena.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/reusing-query-results-1.png) **Para configurar o recurso de reutilização dos resultados da consulta** 1. No editor de consultas do Athena, na opção **Reuse query results** (Reutilizar resultados da consulta), escolha o ícone de edição ao lado de **up to 60 minutes ago** (até 60 minutos atrás). 1. Na caixa de diálogo **Edit reuse time** (Editar tempo de reutilização), na caixa à direita, escolha uma unidade de tempo (minutos, horas ou dias). 1. Na caixa à esquerda, insira ou escolha o número de unidades de tempo que deseja especificar. O tempo máximo que é possível inserir é o equivalente a sete dias, independentemente da unidade de tempo escolhida. ![\[Como configurar o tempo máximo para a reutilização dos resultados da consulta.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/reusing-query-results-2.png) 1. Escolha **Confirmar**. Uma barra de notificação confirmará sua alteração de configuração e a opção **Reuse query results** (Reutilizar resultados da consulta) exibirá a nova configuração. # Visualizar estatísticas e detalhes de execução para consultas concluídas Depois de executar uma consulta, você pode obter estatísticas sobre os dados de entrada e saída processados, ver uma representação gráfica do tempo gasto em cada fase da consulta e explorar os detalhes da execução de maneira interativa. **Para visualizar as estatísticas de uma consulta concluída** 1. Depois de executar uma consulta no editor de consultas do Athena, selecione a guia **Query stats** (Estatísticas da consulta). ![\[Escolha Query stats (Estatísticas da consulta).\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/query-stats-1.png) A guia **Query stats** (Estatísticas de consultas) fornece as seguintes informações: + **Data processed** (Dados processados): mostra o número de linhas de entrada e bytes processados e o número de linhas e bytes gerados. + **The Total runtime** (O tempo de execução total): mostra o tempo total que a consulta levou para ser executada e uma representação gráfica de quanto desse tempo foi gasto em enfileiramento, planejamento, execução e processamento de serviços. **nota** As informações referentes a contagem de linhas e ao tamanho dos dados de entrada e saída em nível de estágio não são mostradas quando uma consulta tem filtros em nível de linha definidos no Lake Formation. 1. Para explorar interativamente as informações sobre como a consulta foi executada, escolha **Execution details** (Detalhes da execução). ![\[Escolha Execution details (Detalhes da execução).\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/query-stats-2.png) A página **Execution details** (Detalhes da execução) mostra o ID de execução da consulta e um gráfico dos estágios baseados em zero nessa consulta. As etapas são ordenadas do início ao fim, de baixo para cima. O rótulo de cada estágio mostra quanto tempo o estágio levou para ser executado. **nota** Em geral, o tempo total de execução e o tempo da fase de execução diferem significativamente. Por exemplo, uma consulta com um tempo de execução total em minutos pode mostrar o tempo da fase de execução em horas. Como uma fase é uma unidade lógica de computação executada paralelamente entre várias tarefas, o tempo de execução de uma fase é o tempo de execução agregado de todas as suas tarefas. Apesar dessa discrepância, o tempo de execução da fase pode ser útil como um indicador relativo de qual fase foi computacionalmente mais intensiva em uma consulta. ![\[A página de detalhes da execução.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/query-stats-3.png) Para navegar pelo gráfico, utilize as seguintes opções: + Para aumentar ou diminuir o zoom, role com o mouse ou use os ícones de ampliação. + Para ajustar o gráfico para que ele caiba na tela, selecione o ícone **Zoom to fit** (Ampliar para caber). + Para mover o gráfico, arraste o ponteiro do mouse. 1. Para ver mais detalhes de um estágio, escolha esse estágio. O painel de detalhes do estágio à direita mostra o número de linhas e bytes de entrada e saída, bem como uma árvore de operador. ![\[Painel de detalhes do estágio.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/query-stats-4.png) 1. Para ver os detalhes do estágio em largura natural, selecione o ícone de expansão na parte superior direita do painel de detalhes. 1. Para obter informações sobre as partes do estágio, expanda um ou mais itens na árvore do operador. ![\[Árvore do operador expandida.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/query-stats-5.png) Para mais informações sobre detalhes de execução, consulte [Noções básicas dos resultados da instrução EXPLAIN do Athena](athena-explain-statement-understanding.md). ## Recursos adicionais Para obter mais informações, consulte os recursos a seguir. [Visualização de planos de execução para consultas SQL](query-plans.md) [Usar EXPLAIN e EXPLAIN ANALYZE no Athena](athena-explain-statement.md) [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/7JUyTqglmNU/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/7JUyTqglmNU) # Trabalhar com visualizações Uma visualização no Amazon Athena é uma tabela lógica, não física. A consulta que define uma exibição é executada sempre que a exibição é referenciada em uma consulta. Você pode criar uma exibição a partir de uma consulta `SELECT` e, em seguida, fazer referência a essa exibição em futuras consultas. É possível usar dois tipos diferentes de visualizações no Athena: visualizações do Athena e visualizações do AWS Glue Data Catalog. ## Quando usar as visualizações do Athena? Talvez você queira criar visualizações do Athena para: + **Consultar um subconjunto de dados**: por exemplo, é possível criar uma visualização com um subconjunto de colunas com base na tabela original para simplificar a consulta de dados. + **Combinar tabelas**: é possível usar exibições para combinar várias tabelas em uma consulta. Se você tem várias tabelas e deseja combiná-las com `UNION ALL`, é possível criar uma visualização com essa expressão para simplificar consultas em tabelas combinadas. + **Ocultar a complexidade**: use as visualizações para ocultar a complexidade de consultas básicas existentes e simplificar as consultas executadas pelos usuários. As consultas básicas geralmente incluem junções entre tabelas, expressões na lista de colunas e outra sintaxe de SQL que dificultam o entendimento e a depuração delas. Você pode criar uma exibição que oculta a complexidade e simplifica consultas. + **Otimizar consultas**: é possível usar visualizações para experimentar técnicas de otimização para criar consultas otimizadas. Por exemplo, se você encontrar uma combinação de condições `WHERE`, ordem `JOIN` ou outras expressões que demonstram a melhor performance, você poderá criar uma exibição com essas cláusulas e expressões. Os aplicativos podem realizar consultas relativamente simples contra essa exibição. Posteriormente, se você encontrar uma melhor maneira de otimizar a consulta original, quando você recriar a exibição, todos os aplicativos aproveitam imediatamente a consulta básica otimizada. + **Ocultar nomes subjacentes**: é possível usar visualizações para ocultar nomes de tabelas e colunas subjacentes e minimizar os problemas de manutenção se esses nomes forem alterados. Se os nomes forem alterados, é possível simplesmente recriar a exibição usando os novos nomes. As consultas que usam a visualização em vez das tabelas continuarão em execução sem alterações. Para obter mais informações, consulte [Trabalhar com visualizações do Athena](views-console.md). ## Quando usar as visualizações do AWS Glue Data Catalog? Use as visualizações do AWS Glue Data Catalog quando desejar uma perspectiva única e comum entre os Serviços da AWS, como o Amazon Athena e o Amazon Redshift. Nas visualizações do Catálogo de Dados, as permissões de acesso são definidas pelo usuário que criou a visualização, e não pelo usuário que consulta a visualização. Esse método de concessão de permissões é chamado de semântica do *programador*. Os casos de uso apresentados a seguir mostram como é possível usar as visualizações do Catálogo de Dados. + **Maior controle de acesso**: você cria uma visualização que restringe o acesso aos dados com base no nível de permissões requeridas pelo usuário. Por exemplo, é possível usar as visualizações do Catálogo de Dados para evitar que colaboradores que não trabalham no departamento de recursos humanos (RH) vejam informações de identificação pessoal. + **Garantia de registros completos**: ao aplicar determinados filtros na visualização do Catálogo de Dados, você garante que os registros de dados em uma visualização do Catálogo de Dados estejam sempre completos. + **Segurança aprimorada**: nas visualizações do Catálogo de Dados, a definição de consulta que cria a visualização deve estar intacta para que a visualização seja criada. Isso torna as visualizações do Catálogo de Dados menos suscetíveis a comandos SQL de agentes mal-intencionados. + **Prevenção do acesso às tabelas subjacentes**: a semântica do programador permite que os usuários acessem uma visualização sem disponibilizar a tabela subjacente para eles. Somente o usuário que define a visualização necessita de acesso às tabelas. As definições de visualização do Catálogo de Dados são armazenadas no AWS Glue Data Catalog. Isso significa que você pode usar o AWS Lake Formation para conceder acesso usando concessões de recursos, concessões de colunas ou controles de acesso baseados em etiquetas. Para obter mais informações sobre como conceder e revogar acesso no Lake Formation, consulte [Granting and revoking permissions on Data Catalog resources](https://docs.aws.amazon.com/lake-formation/latest/dg/granting-catalog-permissions.html) no *Guia do desenvolvedor do AWS Lake Formation*. Para obter mais informações, consulte [Usar visualizações do Catálogo de Dados no Athena](views-glue.md). # Trabalhar com visualizações do Athena As visualizações do Athena podem ser facilmente criadas, atualizadas e gerenciadas no console do Athena. ## Criar visualizações Você pode criar uma visualização no console do Athena usando um modelo ou executando uma consulta existente. **Para usar um modelo para criar uma visualização** 1. No console do Athena, ao lado de **Tables and views** (Tabelas e visualizações), escolha **Create** (Criar) e, em seguida, escolha **Create view** (Criar visualização). ![\[Criação de uma visualização.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/create-view.png) Essa ação coloca um modelo de visualização editável no editor de consultas. 1. Edite o modelo de visualização de acordo com suas necessidades. Quando você digitar um nome para a visualização na instrução, lembre-se de que os nomes das visualizações não podem conter caracteres especiais além do sublinhado `(_)`. Consulte [Nomear bancos de dados, tabelas e colunas](tables-databases-columns-names.md). Evite usar [Escapar palavras-chave reservadas em consultas](reserved-words.md) para nomear visualizações. Para obter mais informações sobre a criação de visualizações, consulte [CREATE VIEW e da CREATE PROTECTED MULTI DIALECT VIEW](create-view.md) e [Exemplos de visualizações do Athena](views-examples.md). 1. Selecione **Run** (Executar) para criar a visualização. A visualização aparece na lista de visualizações no console do Athena. **Para criar uma visualização a partir de uma consulta existente** 1. Use o editor de consultas do Athena para executar uma consulta existente. 1. Na janela do editor de consultas, escolha **Create** (Criar) e, em seguida, escolha **View from query** (Visualização a partir de consulta). ![\[Selecione Create (Criar), View from query (Visualização a partir de consulta).\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/create-view-from-query.png) 1. Na caixa de diálogo **Create View** (Criar visualização), insira um nome para a visualização e, em seguida, escolha **Create** (Criar). Os nomes de visualizações não podem conter caracteres especiais, exceto sublinhado `(_)`. Consulte [Nomear bancos de dados, tabelas e colunas](tables-databases-columns-names.md). Evite usar [Escapar palavras-chave reservadas em consultas](reserved-words.md) para nomear visualizações. O Athena adiciona a visualização à lista de visualizações no console e exibe a instrução `CREATE VIEW` para a visualização no editor de consulta. **Observações** + Se você excluir uma tabela em que outra tabela se baseia e, depois, tentar executar a visualização, o Athena exibirá uma mensagem de erro. + Você pode criar uma visualização aninhada, que fica acima de uma visualização existente. O Athena impede que você execute uma visualização repetida com referência a ela mesma. # Exemplos de visualizações do Athena Para mostrar a sintaxe da consulta de exibição, use [SHOW CREATE VIEW](show-create-view.md). **Example Exemplo 1** Considere as duas tabelas a seguir: uma tabela `employees` com duas colunas, `id` e `name` e uma tabela `salaries`com duas colunas, `id` e `salary`. Neste exemplo, criamos uma exibição chamada `name_salary` como uma consulta `SELECT` que obtém uma lista de IDs mapeados para salários a partir das tabelas `employees` e `salaries`: ``` CREATE VIEW name_salary AS SELECT employees.name, salaries.salary FROM employees, salaries WHERE employees.id = salaries.id ``` **Example Exemplo 2** No exemplo a seguir, criamos uma exibição chamada `view1` que permite que você oculte a sintaxe de consulta mais complexa. Essa exibição é executada sobre duas tabelas, `table1` e `table2`, em que cada tabela é uma consulta `SELECT` diferente. A visualização seleciona as colunas de `table1` e combina os resultados com `table2`. A junção é baseada na coluna `a` presente em ambas as tabelas. ``` CREATE VIEW view1 AS WITH table1 AS ( SELECT a, MAX(b) AS the_max FROM x GROUP BY a ), table2 AS ( SELECT a, AVG(d) AS the_avg FROM y GROUP BY a) SELECT table1.a, table1.the_max, table2.the_avg FROM table1 JOIN table2 ON table1.a = table2.a; ``` Para obter informações sobre consultar visualizações federadas, consulte [Consultar visualizações federadas](running-federated-queries.md#running-federated-queries-federated-views). # Gerenciar visualizações do Athena No console do Athena, é possível: + Localizar todas as visualizações no painel esquerdo, onde as tabelas estão listadas. + Filtre as exibições. + Visualize uma exibição, mostre suas propriedades, edite-a ou exclua-a. **Para mostrar as ações de uma exibição** Uma exibição é mostrada no console somente se você já a criou. 1. No console do Athena, escolha **Views** (Visualizações) e, em seguida, escolha uma visualização para expandi-la e mostrar as colunas na visualização. 1. Escolha os três pontos verticais ao lado da visualização para mostrar uma lista de ações dela. ![\[O menu de ações de uma visualização.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/view-options.png) 1. Escolha as ações para a visualização: exibir uma prévia, inserir o nome o editor de consultas, excluir, consultar as propriedades ou exibir e editar no editor de consultas. ## Ações do DDL com suporte para visualizações do Athena O Athena oferece suporte às ações a seguir nas visualizações. | Declaração | Descrição | | --- | --- | | [CREATE VIEW e da CREATE PROTECTED MULTI DIALECT VIEW](create-view.md) | Cria uma nova exibição a partir de uma consulta `SELECT` especificada. Para obter mais informações, consulte [Criar visualizações](views-console.md#creating-views). A cláusula `OR REPLACE` opcional permite atualizar a exibição existente substituindo-a | | [DESCRIBE VIEW](describe-view.md) | Mostra a lista de colunas para a exibição nomeada. Isso permite examinar os atributos de uma exibição complexa. | | [DROP VIEW](drop-view.md) | Exclui uma exibição existente. A cláusula `IF EXISTS` opcional suprime o erro se a exibição não existir. | | [SHOW CREATE VIEW](show-create-view.md) | Mostra a instrução SQL que cria a exibição específica. | | [SHOW VIEWS](show-views.md) | Lista as exibições no banco de dados especificado ou no banco de dados atual se você omitir o nome do banco de dados. Use a cláusula `LIKE` opcional com uma expressão regular para restringir a lista de nomes de exibições. Você também pode ver a lista de exibições no painel esquerdo no console. | | [SHOW COLUMNS](show-columns.md) | Liste as colunas no esquema para obter uma visualização. | # Considerações e limitações das visualizações do Athena As visualizações do Athena têm considerações e limitações a seguir. ## Considerações As seguintes considerações se aplicam à criação e ao uso de visualizações no Athena: + No Athena, é possível pré-visualizar e trabalhar com visualizações criadas no console do Athena, no AWS Glue Data Catalog ou com o Presto em execução no cluster do Amazon EMR conectado ao mesmo catálogo. + Se você criou visualizações do Athena no catálogo de dados, o catálogo as trata como tabelas. Você pode usar o controle de acesso detalhado no nível da tabela no catálogo de dados para [restringir o acesso](fine-grained-access-to-glue-resources.md) a essas visualizações. + O Athena impede que você execute visualizações repetidas e exibe uma mensagem de erro nesses casos. Uma exibição recursiva é uma consulta de exibição que faz referência a si mesmo. + O Athena exibe uma mensagem de erro quando detecta visualizações obsoletas. Uma exibição obsoleta é relatada quando um dos seguintes itens ocorrer: + A exibição faz referência a tabelas ou bancos de dados que não existem. + Uma alteração de esquema ou metadados é feita em uma tabela referenciada. + Uma tabela referenciada é descartada e recriada com um esquema ou uma configuração diferente. + Você pode criar e executar exibições aninhadas, desde que a consulta por trás da exibição aninhada seja válida e as tabelas e os bancos de dados existirem. ## Limitações + Os nomes das visualizações do Athena não podem conter caracteres especiais, exceto sublinhado `(_)`. Para obter mais informações, consulte [Nomear bancos de dados, tabelas e colunas](tables-databases-columns-names.md). + Evite usar palavras-chave reservadas para nomear visualizações. Se você usar palavras-chave reservadas, use aspas duplas para delimitar as palavras-chave reservadas em suas consultas em visualizações. Consulte [Escapar palavras-chave reservadas em consultas](reserved-words.md). + Não é possível usar visualizações criadas no Athena com metastores externos do Hive ou UDFs. Para obter informações sobre como trabalhar com visualizações criadas externamente no Hive, consulte [Trabalhar com visualizações do Hive](hive-views.md). + Não é possível usar visualizações com funções geoespaciais. + Não é possível usar as visualizações para gerenciar o controle de acesso aos dados no Amazon S3. Para consultar uma visualização, é necessário ter permissões para acessar os dados armazenados no Amazon S3. Para obter mais informações, consulte [Controlar o acesso ao Amazon S3 do Athena](s3-permissions.md). + Embora as consultas de visualizações entre contas seja possível no mecanismo do Athena versão 3, não é possível criar uma visualização que inclua um AWS Glue Data Catalog entre contas. Para obter informações sobre o acesso a catálogos de dados entre contas, consulte [Configurar o acesso entre contas aos catálogos de dados do AWS Glue](security-iam-cross-account-glue-catalog-access.md). + As colunas ocultas de metadados do Hive ou Iceberg `$bucket`, `$file_modified_time`, `$file_size` e `$partition` não são compatíveis para visualizações no Athena. Para obter informações sobre como usar a coluna `$path` de metadados no Athena, consulte [Obter os locais de arquivos dos dados de origem no Amazon S3](select.md#select-path). # Usar visualizações do Catálogo de Dados no Athena A criação de visualizações do catálogo de dados no Amazon Athena exige uma instrução `CREATE VIEW` especial. Consultá-las usa a sintaxe `SELECT` do SQL convencional. As visualizações do Catálogo de Dados também são chamadas de visualizações de *vários dialetos*, ou MDVs. ## Criar uma visualização do Catálogo de Dados Para criar uma visualização do Catálogo de Dados no Athena, use a sintaxe a seguir. ``` CREATE [ OR REPLACE ] PROTECTED MULTI DIALECT VIEW view_name SECURITY DEFINER [ SHOW VIEW JSON ] AS athena-sql-statement ``` **nota** A opção `SHOW VIEW JSON` se aplica somente às visualizações do Catálogo de Dados, e não às visualizações do Athena. O uso da opção `SHOW VIEW JSON` inicia uma "execução seca" que valida a entrada e, se a validação for bem-sucedida, retornará o JSON do objeto da tabela AWS Glue que representará a visualização. A visualização real não é criada. Se a opção `SHOW VIEW JSON` não for especificada, as validações serão feitas e a exibição será criada normalmente no Catálogo de Dados. O exemplo de sintaxe apresentado a seguir mostra como um usuário do perfil `Definer` cria a visualização `orders_by_date` do Catálogo de Dados. O exemplo pressupõe que o perfil `Definer` tenha permissões `SELECT` completas na tabela `orders` no banco de dados `default`. ``` CREATE PROTECTED MULTI DIALECT VIEW orders_by_date SECURITY DEFINER AS SELECT orderdate, sum(totalprice) AS price FROM orders WHERE order_city = 'SEATTLE' GROUP BY orderdate ``` Para obter informações sobre sintaxe, consulte [CREATE PROTECTED MULTI DIALECT VIEW](create-view.md#create-protected-multi-dialect-view). ## Consulta de uma visualização do Catálogo de Dados Depois que a visualização for criada, o admin do `Lake Formation` poderá conceder permissões `SELECT` na visualização do Catálogo de Dados para as entidades principais do `Invoker`. Em seguida, as entidades principais do `Invoker` poderão consultar a visualização sem ter acesso às tabelas subjacentes básicas referenciadas pela visualização. Veja a seguir um exemplo de consulta do `Invoker`. ``` SELECT * from orders_by_date where price > 5000 ``` ## Considerações e limitações A maioria das limitações de visualização a seguir do Catálogo de Dados são específicas do Athena. Para ver limitações adicionais das visualizações do Catálogo de Dados que se também aplicam a outros serviços, consulte a documentação do Lake Formation. + As visualizações do catálogo de dados não podem referenciar outras visualizações, links de recursos de banco de dados ou links de recursos de tabela. + É possível fazer referência a até dez tabelas na definição de visualização. + As tabelas não devem ter a permissão de data lake `IAMAllowedPrincipals` no Lake Formation. Se presente, o erro Visualizações de vários dialetos só podem fazer referência a tabelas sem permissões de IAMAllowedPrincipals permissions ocorrerá. + A localização da tabela no Amazon S3 deve ser registrada como uma localização de data lake do Lake Formation. Se a tabela não estiver registrada dessa forma, o erro Visualizações de vários dialetos só podem fazer referência a tabelas gerenciadas pelo Lake Formation ocorrerá. Para obter informações sobre como registrar locais do Amazon S3 no Lake Formation, consulte [Registrar um local do Amazon S3](https://docs.aws.amazon.com/lake-formation/latest/dg/register-location.html) no *Guia do desenvolvedor do AWS Lake Formation*. + As chamadas das APIs [GetTables](https://docs.aws.amazon.com/glue/latest/webapi/API_GetTables.html) e [SearchTables](https://docs.aws.amazon.com/glue/latest/webapi/API_SearchTables.html) do AWS Glue não atualizam o parâmetro `IsRegisteredWithLakeFormation`. Para visualizar o valor correto para o parâmetro, use a API [GetTable](https://docs.aws.amazon.com/glue/latest/webapi/API_GetTable.html) do AWS Glue. Para obter mais informações, consulte [As APIs GetTables e SearchTables não atualizam o valor do parâmetro IsRegisteredWithLakeFormation](https://docs.aws.amazon.com/lake-formation/latest/dg/limitations.html#issue-GetTables-value) no *Guia do desenvolvedor do AWS Lake Formation*. + A entidade principal `DEFINER` pode ser somente um perfil do IAM. + O perfil `DEFINER` deve ter permissões `SELECT` completas (concedíveis) nas tabelas subjacentes. + Não há suporte para as visualizações `UNPROTECTED` do Catálogo de Dados. + Não há suporte para as funções definidas pelo usuário (UDFs) na definição de visualização. + As fontes de dados federadas do Athena não podem ser usadas em visualizações do Catálogo de Dados. + As visualizações do Catálogo de Dados não têm suporte para metastores externos do Hive. + O Athena exibe uma mensagem de erro quando detecta visualizações obsoletas. Uma exibição obsoleta é relatada quando um dos seguintes itens ocorrer: + A exibição faz referência a tabelas ou bancos de dados que não existem. + Uma alteração de esquema ou metadados é feita em uma tabela referenciada. + Uma tabela referenciada é descartada e recriada com um esquema ou uma configuração diferente. ## Permissões As visualizações do Catálogo de Dados requerem três perfis: `Lake Formation Admin`, `Definer` e `Invoker`. + **`Lake Formation Admin`** – tem acesso para configurar todas as permissões do Lake Formation. + **`Definer`** – cria a visualização do Catálogo de Dados. O perfil `Definer` deve ter permissões `SELECT` completas e concedíveis em todas as tabelas subjacentes às quais a definição de visualização faz referência. + **`Invoker`** – pode consultar a visualização do Catálogo de Dados ou verificar seus metadados. Para mostrar o invocador de uma consulta, você pode usar a função `invoker_principal()` do DML. Para obter mais informações, consulte [invoker\$1principal()](functions-env3.md#functions-env3-invoker-principal). As relações de confiança do perfil `Definer` devem permitir a ação `sts:AssumeRole` para as entidades principais de serviço do AWS Glue e do Lake Formation. Para obter mais informações, consulte [Pré-requisitos para a criação de visualizações](https://docs.aws.amazon.com/lake-formation/latest/dg/working-with-views.html#views-prereqs) no *Guia do desenvolvedor do AWS Lake Formation*. As permissões do IAM para o acesso ao Athena também são necessárias. Para obter mais informações, consulte [AWSPoliticas gerenciadas pela para o Amazon Athena](security-iam-awsmanpol.md). # Gerenciamento de visualizações do Catálogo de Dados É possível usar comandos DDL para atualizar e gerenciar suas visualizações do Catálogo de Dados. ## Atualização de uma visualização do Catálogo de Dados O admin do `Lake Formation` ou o definidor podem usar a sintaxe do `ALTER VIEW UPDATE DIALECT` para atualizar a definição de visualização. O exemplo apresentado a seguir modifica a definição de visualização para selecionar colunas da tabela `returns` em vez de usar a tabela `orders`. ``` ALTER VIEW orders_by_date UPDATE DIALECT AS SELECT return_date, sum(totalprice) AS price FROM returns WHERE order_city = 'SEATTLE' GROUP BY orderdate ``` ## Ações do DDL com suporte para visualizações do AWS Glue Data Catalog O Athena oferece suporte às ações a seguir nas visualizações do AWS Glue Data Catalog. | Declaração | Descrição | | --- | --- | | [ALTER VIEW DIALECT](alter-view-dialect.md) | Atualiza uma visualização do Catálogo de Dados adicionando um dialeto para o mecanismo ou atualizando ou descartando um dialeto do mecanismo existente. | | [CREATE PROTECTED MULTI DIALECT VIEW](create-view.md#create-protected-multi-dialect-view) | Cria uma visualização do Catálogo de Dados a partir de uma consulta `SELECT` especificada. Para obter mais informações, consulte [CREATE PROTECTED MULTI DIALECT VIEW](create-view.md#create-protected-multi-dialect-view). A cláusula `OR REPLACE` opcional permite atualizar a exibição existente substituindo-a | | [DESCRIBE VIEW](describe-view.md) | Mostra a lista de colunas para a exibição nomeada. Isso permite examinar os atributos de uma exibição complexa. | | [DROP VIEW](drop-view.md) | Exclui uma exibição existente. A cláusula `IF EXISTS` opcional suprime o erro se a exibição não existir. | | [SHOW CREATE VIEW](show-create-view.md) | Mostra a instrução SQL que cria a exibição específica. | | [SHOW VIEWS](show-views.md) | Lista as exibições no banco de dados especificado ou no banco de dados atual se você omitir o nome do banco de dados. Use a cláusula `LIKE` opcional com uma expressão regular para restringir a lista de nomes de exibições. Você também pode ver a lista de exibições no painel esquerdo no console. | | [SHOW COLUMNS](show-columns.md) | Liste as colunas no esquema para obter uma visualização. | # Usar consultas salvas É possível usar o console do Athena para salvar, editar, executar, renomear e excluir consultas criadas no editor de consultas. ## Considerações e limitações + É possível atualizar o nome, a descrição e o texto de consultas salvas. + Apenas é possível atualizar as consultas na sua própria conta. + Você não pode alterar o grupo de trabalho ou o banco de dados ao qual essa consulta pertence. + O Athena não mantém um histórico de modificações de consultas. Se quiser manter uma versão específica de uma consulta, salve-a com um nome diferente. **nota** Os recursos do Amazon Athena agora podem ser acessados no Estúdio Unificado Amazon SageMaker (Preview), o que ajuda você a acessar os dados da sua organização e agir com base neles usando as melhores ferramentas. É possível migrar consultas salvas de um grupo de trabalho do Athena para um projeto do SageMaker Unified Studio, configurar projetos com grupos de trabalho existentes do Athena e manter as permissões necessárias por meio de atualizações de perfis do IAM. Para obter mais informações, consulte [Migrar recursos do Amazon Athena para o Estudio Unificado Amazon SageMaker (Preview)](https://github.com/aws/Unified-Studio-for-Amazon-Sagemaker/tree/main/migration/athena). **Topics** + [Considerações e limitações](#saved-queries-considerations-and-limitations) + [Salvar uma consulta com um nome](saved-queries-name.md) + [Executar uma consulta salva](saved-queries-run.md) + [Editar uma consulta salva](saved-queries-edit.md) + [Renomear ou excluir uma consulta salva](saved-queries-rename-or-delete.md) + [Renomear uma consulta salva não exibida](saved-queries-rename-not-displayed.md) + [Excluir uma consulta salva não exibida](saved-queries-delete-not-displayed.md) + [Usar a API do Athena para atualizar consultas salvas](saved-queries-update-with-api.md) # Salvar uma consulta com um nome **Para salvar uma consulta e dar um nome para ela** 1. Insira ou execute uma consulta no editor de consultas do console do Athena. 1. Acima da janela do editor de consultas, na guia para a consulta, selecione os três pontos verticais e, em seguida, escolha **Save as** (Salvar como). 1. Na caixa de diálogo **Save query** (Salvar consulta), insira um nome para a consulta e uma descrição opcional. Você pode usar a janela expansível **Preview SQL query** (Visualizar consulta SQL) para verificar o conteúdo da consulta antes de a salvar. 1. Escolha **Save query** (Salvar consulta). No editor de consultas, a guia referente à consulta mostra o nome especificado. # Executar uma consulta salva **Como executar uma consulta salva** 1. No console do Athena, escolha a guia **Saved queries** (Consultas salvas). 1. Na lista **Saved queries** (Consultas salvas), escolha o ID da consulta que deseja executar. O editor de consultas mostra a consulta escolhida. 1. Escolha **Executar**. # Editar uma consulta salva **Para editar uma consulta salva** 1. No console do Athena, escolha a guia **Saved queries** (Consultas salvas). 1. Na lista **Saved queries** (Consultas salvas), escolha o ID da consulta que deseja editar. 1. Edite consulta no editor de consultas. 1. Execute uma das seguintes etapas: + Para executar a consulta, escolha **Run** (Executar). + Para salvar a consulta, selecione os três pontos verticais na guia para a consulta e, em seguida, escolha **Save** (Salvar). + Para salvar a consulta com um nome diferente, selecione os três pontos verticais na guia para a consulta e, em seguida, escolha **Save as** (Salvar como). # Renomear ou excluir uma consulta salva **Para renomear ou excluir uma consulta salva já exibida no editor de consultas** 1. Selecione os três pontos verticais na guia para a consulta e, em seguida, escolha **Rename** (Renomear) ou **Delete** (Excluir). 1. Siga as solicitações para renomear ou excluir a consulta. # Renomear uma consulta salva não exibida **Para renomear uma consulta salva não exibida no editor de consultas** 1. No console do Athena, escolha a guia **Saved queries** (Consultas salvas). 1. Marque a caixa de seleção referente à consulta que você deseja renomear. 1. Escolha **Rename (Renomear)**. 1. Na caixa de diálogo **Rename query** (Renomear consulta), edite o nome da consulta e sua descrição. Você pode usar a janela expansível **Preview SQL query** (Visualizar consulta SQL) para verificar o conteúdo da consulta antes de a renomear. 1. Escolha **Rename query** (Renomear consulta). A consulta renomeada aparece na lista **Saved queries** (Consultas salvas). # Excluir uma consulta salva não exibida **Para excluir uma consulta salva não exibida no editor de consultas** 1. No console do Athena, escolha a guia **Saved queries** (Consultas salvas). 1. Marque uma ou mais das caixas de seleção referentes às consultas que você deseja excluir. 1. Escolha **Excluir**. 1. No prompt de confirmação, selecione **Excluir**. Uma ou mais consultas serão removidas da lista **Saved queries** (Consultas salvas). # Usar a API do Athena para atualizar consultas salvas Para informações sobre o uso da API do Athena para atualizar uma consulta salva, consulte a ação [UpdateNamedQuery](https://docs.aws.amazon.com/athena/latest/APIReference/API_UpdateNamedQuery.html) na Referência de APIs Athena. # Usar consultas parametrizadas É possível utilizar consultas parametrizadas do Athena para repetir a execução da mesma consulta com valores de parâmetros diferentes no momento da execução e ajudar a evitar ataques de injeção de SQL. No Athena, consultas parametrizadas podem assumir a forma de parâmetros de execução em qualquer consulta DML ou instruções preparadas para SQL. + Consultas com parâmetros de execução podem ser feitas em uma única etapa e não são específicas para um grupo de trabalho. Coloque pontos de interrogação em qualquer consulta DML para os valores que você deseja parametrizar. Ao executar a consulta, declare os valores do parâmetro de execução sequencialmente. A declaração de parâmetros e a atribuição de valores para esses parâmetros podem ser feitas na mesma consulta, mas de maneira dissociada. Ao contrário de instruções preparadas, é possível selecionar o grupo de trabalho ao enviar uma consulta com parâmetros de execução. + Instruções preparadas exigem duas instruções SQL separadas: `PREPARE` e `EXECUTE`. Primeiro, você define os parâmetros na instrução `PREPARE`. Em seguida, executa uma instrução `EXECUTE` que fornece os valores dos parâmetros definidos. Instruções preparadas são específicas de um grupo de trabalho, ou seja, não podem ser executadas fora do contexto do grupo de trabalho ao qual pertencem. ## Considerações e limitações + Há compatibilidade com consultas parametrizadas no mecanismo do Athena versão 2 e versões posteriores. Para obter informações sobre as versões do mecanismo do Athena, consulte [Versionamento do mecanismo do Athena](engine-versions.md). + Atualmente, as consultas parametrizadas são aceitas apenas nas instruções `SELECT`, `INSERT INTO`, `CTAS` e `UNLOAD`. + Em consultas parametrizadas, parâmetros são posicionais e representados por`?`. Parâmetros recebem valores de acordo com sua ordem na consulta. Não há suporte para parâmetros nomeados. + No momento, parâmetros `?` podem ser inseridos somente na cláusula `WHERE`. Não há suporte para a sintaxe do tipo `SELECT ? FROM table`. + Parâmetros de ponto de interrogação não podem ser inseridos entre aspas duplas ou simples (ou seja, `'?'` e `"?"` não são uma sintaxe válida). + Para que os parâmetros de execução do SQL sejam tratados como strings, eles devem estar entre aspas simples em vez de aspas duplas. + Se necessário, você pode usar a função `CAST` ao inserir um valor para um termo parametrizado. Por exemplo, se você tiver uma coluna do tipo `date` parametrizada em uma consulta e quiser consultar a data `2014-07-05`, inserir `CAST('2014-07-05' AS DATE)` como valor do parâmetro retornará o resultado. + Instruções preparadas são específicas de um grupo de trabalho, e seus nomes devem ser exclusivos no grupo de trabalho. + São necessárias permissões do IAM para as instruções preparadas. Para obter mais informações, consulte [Configurar o acesso a instruções preparadas](security-iam-athena-prepared-statements.md). + Consultas com parâmetros de execução no console do Athena estão limitadas a um máximo de 25 pontos de interrogação. **Topics** + [Considerações e limitações](#querying-with-prepared-statements-considerations-and-limitations) + [Usar parâmetros de execução](querying-with-prepared-statements-querying-using-execution-parameters.md) + [Usar instruções preparadas](querying-with-prepared-statements-querying.md) + [Recursos adicionais](querying-with-prepared-statements-additional-resources.md) # Usar parâmetros de execução É possível utilizar espaços reservados de ponto de interrogação em qualquer consulta DML para criar uma consulta parametrizada sem criar uma instrução preparada primeiro. Para executar essas consultas, use o console do Athena, a AWS CLI ou o AWS SDK e declare as variáveis no argumento `execution-parameters`. **Topics** + [Usar o console do Athena](querying-with-prepared-statements-running-queries-with-execution-parameters-in-the-athena-console.md) + [Usar a AWS CLI](querying-with-prepared-statements-running-queries-with-execution-parameters-using-the-aws-cli.md) # Executar consultas com parâmetros de execução no console do Athena Ao executar uma consulta parametrizada com parâmetros de execução (pontos de interrogação) no console do Athena, você deve informar os valores na ordem em que os pontos de interrogação ocorrem nessa consulta. **Para executar uma consulta com parâmetros de execução** 1. Insira uma consulta com espaços reservados de ponto de interrogação no editor do Athena, como no seguinte exemplo. ``` SELECT * FROM "my_database"."my_table" WHERE year = ? and month= ? and day= ? ``` 1. Escolha **Executar**. 1. Na caixa de diálogo **Enter parameters** (Inserir parâmetros), insira um valor em ordem para cada um dos pontos de interrogação na consulta. ![\[Insira valores para os parâmetros de consulta em ordem\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-with-prepared-statements-1.png) 1. Quando terminar de inserir os parâmetros, escolha **Run** (Executar). O editor mostra os resultados da consulta para os valores de parâmetro inseridos. Nesse ponto, você pode realizar uma das seguintes ações: + Insira valores de parâmetros diferentes para a mesma consulta e escolha **Run again** (Execute novamente). + Para limpar todos os valores inseridos de uma só vez, escolha **Clear** (Limpar). + Para editar a consulta diretamente (por exemplo, para adicionar ou remover pontos de interrogação), feche primeiro a caixa de diálogo **Enter parameters** (Inserir parâmetros). + Para salvar a consulta parametrizada para uso posterior, escolha **Save** (Salvar) ou **Save as** (Salvar como) e depois dê um nome para ela. Para obter mais informações sobre o uso de consultas salvas, consulte [Usar consultas salvas](saved-queries.md). Como conveniência, a caixa de diálogo **Enter parameters** (Inserir parâmetros) memoriza os valores inseridos anteriormente para a consulta, desde que você utilize a mesma guia no editor de consultas. # Executar consultas com parâmetros de execução com a AWS CLI Para usar a AWS CLI para executar consultas com parâmetros de execução, use o comando `start-query-execution` e forneça uma consulta parametrizada no argumento `query-string`. Em seguida, no argumento `execution-parameters`, forneça os valores para os parâmetros de execução. O exemplo a seguir ilustra essa técnica. ``` aws athena start-query-execution --query-string "SELECT * FROM table WHERE x = ? AND y = ?" --query-execution-context "Database"="default" --result-configuration "OutputLocation"="s3://amzn-s3-demo-bucket;/..." --execution-parameters "1" "2" ``` # Usar instruções preparadas Você pode usar uma instrução preparada para a execução repetida da mesma consulta com diferentes parâmetros de consulta. Uma instrução preparada contém espaços reservados de parâmetros dos quais os valores são fornecidos no runtime. **nota** O número máximo de instruções preparadas em um grupo de trabalho é mil. **Topics** + [Sintaxe de SQL](querying-with-prepared-statements-sql-statements.md) + [Usar o console do Athena](querying-with-prepared-statements-executing-prepared-statements-without-the-using-clause-athena-console.md) + [Usar a AWS CLI](querying-with-prepared-statements-cli-section.md) # Sintaxe de SQL para instruções preparadas É possível utilizar as instruções SQL `PREPARE`, `EXECUTE` e `DEALLOCATE PREPARE` para executar consultas parametrizadas no editor de consultas do console do Athena. + Para especificar parâmetros nos quais você costuma usar valores literais, use pontos de interrogação na instrução `PREPARE`. + Para substituir os parâmetros por valores quando você executar a consulta, use a cláusula `USING` na instrução `EXECUTE`. + Para remover uma instrução preparada do conjunto de instruções preparadas em um grupo de trabalho, use a instrução `DEALLOCATE PREPARE`. As seções a seguir apresentam mais detalhes sobre cada uma dessas instruções. **Topics** + [PREPARE](querying-with-prepared-statements-prepare.md) + [EXECUTE](querying-with-prepared-statements-execute.md) + [DEALLOCATE PREPARE](querying-with-prepared-statements-deallocate-prepare.md) # PREPARE Prepara uma instrução para execução futura. As instruções preparadas são salvas no grupo de trabalho atual com o nome que você especificar. A instrução pode incluir parâmetros no lugar de literais para serem substituídos quando a consulta for executada. Os parâmetros que serão substituídos por valores são indicados por pontos de interrogação. ## Sintaxe ``` PREPARE statement_name FROM statement ``` A tabela a seguir descreve esses parâmetros. **** | Parameter | Descrição | | --- | --- | | statement\$1name | O nome da instrução que será preparada. O nome deve ser exclusivo no grupo de trabalho. | | instrução | Uma consulta SELECT, CTAS ou INSERT INTO. | ## Exemplos de PREPARE Os exemplos a seguir mostram o uso da instrução `PREPARE`. Os pontos de interrogação indicam os valores que serão inseridos pela instrução `EXECUTE` quando a consulta for executada. ``` PREPARE my_select1 FROM SELECT * FROM nation ``` ``` PREPARE my_select2 FROM SELECT * FROM "my_database"."my_table" WHERE year = ? ``` ``` PREPARE my_select3 FROM SELECT order FROM orders WHERE productid = ? and quantity < ? ``` ``` PREPARE my_insert FROM INSERT INTO cities_usa (city, state) SELECT city, state FROM cities_world WHERE country = ? ``` ``` PREPARE my_unload FROM UNLOAD (SELECT * FROM table1 WHERE productid < ?) TO 's3://amzn-s3-demo-bucket/' WITH (format='PARQUET') ``` # EXECUTE Executa uma instrução preparada. Os valores dos parâmetros são especificados na cláusula `USING`. ## Sintaxe ``` EXECUTE statement_name [USING value1 [ ,value2, ... ] ] ``` *statement\$1name* é o nome da instrução preparada. *value1* e *value2* são os valores que serão especificados para os parâmetros na instrução. ## Exemplos de EXECUTE O exemplo a seguir executa a instrução preparada `my_select1`, que não contém parâmetros. ``` EXECUTE my_select1 ``` O exemplo a seguir executa a instrução preparada `my_select2`, que contém um único parâmetro. ``` EXECUTE my_select2 USING 2012 ``` O exemplo a seguir executa a instrução preparada `my_select3`, que contém dois parâmetros. ``` EXECUTE my_select3 USING 346078, 12 ``` O exemplo a seguir fornece um valor de string para um parâmetro na instrução preparada `my_insert`. ``` EXECUTE my_insert USING 'usa' ``` O exemplo a seguir fornece um valor numérico para o parâmetro `productid` na instrução preparada `my_unload`. ``` EXECUTE my_unload USING 12 ``` # DEALLOCATE PREPARE Remove a instrução preparada com o nome especificado da lista de instruções preparadas no grupo de trabalho atual. ## Sintaxe ``` DEALLOCATE PREPARE statement_name ``` *statement\$1name* é o nome da instrução preparada que será removida. ## Exemplo O exemplo a seguir remove a instrução preparada `my_select1` do grupo de trabalho atual. ``` DEALLOCATE PREPARE my_select1 ``` # Executar instruções preparadas e interativas no console do Athena Se você executar uma instrução preparada existente com a sintaxe `EXECUTE` *prepared\$1statement* no editor de consultas, o Athena abrirá a caixa de diálogo **Enter parameters** (Inserir parâmetros), para que seja possível inserir os valores que normalmente entrariam na cláusula `USING` da instrução `EXECUTE ... USING`. **Para executar uma instrução preparada usando a caixa de diálogo **Enter parameters** (Inserir parâmetros)** 1. No editor de consultas, em vez de usar a sintaxe `EXECUTE prepared_statement USING` *value1*`,` *value2* ` ...`, use a sintaxe `EXECUTE` *prepared\$1statement*. 1. Escolha **Executar**. A caixa de diálogo **Enter parameters** (Inserir parâmetros) é exibida. ![\[Inserir valores de parâmetros para uma instrução preparada no console do Athena\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-with-prepared-statements-2.png) 1. Insira os valores em ordem na caixa de diálogo **Execution parameters** (Parâmetros de execução). Como o texto original da consulta não está visível, você deve se lembrar do significado de cada parâmetro posicional ou ter a instrução preparada disponível para referência. 1. Escolha **Executar**. # Usar a AWS CLI para criar, executar e listar instruções preparadas É possível usar a AWS CLI para criar, executar e listar instruções preparadas. **Topics** + [Criar](querying-with-prepared-statements-creating-prepared-statements-using-the-aws-cli.md) + [Execute](querying-with-prepared-statements-cli-executing-prepared-statements.md) + [Lista](querying-with-prepared-statements-listing.md) # Criar instruções preparadas com o uso da AWS CLI Para usar a AWS CLI para criar uma instrução preparada, é possível utilizar um dos seguintes comandos `athena`: + Use o comando `create-prepared-statement` e forneça uma instrução de consulta que tenha parâmetros de execução. + Use o comando `start-query-execution` e forneça uma string de consulta que use a sintaxe `PREPARE`. ## Usar create-prepared-statement Em um comando `create-prepared-statement`, defina o texto da consulta no argumento `query-statement`, como no exemplo a seguir. ``` aws athena create-prepared-statement --statement-name PreparedStatement1 --query-statement "SELECT * FROM table WHERE x = ?" --work-group athena-engine-v2 ``` ## Usar start-query-execution e a sintaxe PREPARE Use o comando `start-query-execution`. Coloque a instrução `PREPARE` no argumento `query-string`, como no exemplo a seguir: ``` aws athena start-query-execution --query-string "PREPARE PreparedStatement1 FROM SELECT * FROM table WHERE x = ?" --query-execution-context '{"Database": "default"}' --result-configuration '{"OutputLocation": "s3://amzn-s3-demo-bucket/..."}' ``` # Executar instruções preparadas com o uso da AWS CLI Para executar uma declaração preparada com a AWS CLI, forneça valores para os parâmetros com um dos seguintes métodos: + Use o argumento `execution-parameters`. + Use a sintaxe SQL `EXECUTE ... USING` no argumento `query-string`. ## Usar o argumento execution-parameters Nessa abordagem, você usa o comando `start-query-execution` e fornece o nome de uma declaração preparada existente no argumento `query-string`. Em seguida, no argumento `execution-parameters`, forneça os valores para os parâmetros de execução. O exemplo a seguir mostra esse método. ``` aws athena start-query-execution --query-string "Execute PreparedStatement1" --query-execution-context "Database"="default" --result-configuration "OutputLocation"="s3://amzn-s3-demo-bucket/..." --execution-parameters "1" "2" ``` ## Usar EXECUTE ... USING Para executar uma instrução preparada existente usando a sintaxe `EXECUTE ... USING`, use o comando `start-query-execution` e coloque o nome da instrução preparada e os valores do parâmetro no argumento `query-string`, como no exemplo a seguir: ``` aws athena start-query-execution --query-string "EXECUTE PreparedStatement1 USING 1" --query-execution-context '{"Database": "default"}' --result-configuration '{"OutputLocation": "s3://amzn-s3-demo-bucket/..."}' ``` # Listar instruções preparadas com o uso da AWS CLI Para listar as instruções preparadas para um grupo de trabalho específico, use o comando [list-prepared-statements](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/athena/list-prepared-statements.html) da AWS CLI do Athena ou a ação de API [ListPreparedStatements](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListPreparedStatements.html) do Athena. O parâmetro `--work-group` é obrigatório. ``` aws athena list-prepared-statements --work-group primary ``` # Recursos adicionais Veja as seguintes postagens relacionadas no blog de Big Data da AWS. + [Improve reusability and security using Amazon Athena parameterized queries](https://aws.amazon.com/blogs/big-data/improve-reusability-and-security-using-amazon-athena-parameterized-queries/) + [Use Amazon Athena parameterized queries to provide data as a service](https://aws.amazon.com/blogs/big-data/use-amazon-athena-parameterized-queries-to-provide-data-as-a-service/) # Usar o otimizador baseado em custos Você pode usar o atributo otimizador baseado em custos (CBO) no Athena SQL para otimizar as consultas. Opcionalmente, você pode solicitar que o Athena colete estatísticas no nível da tabela ou da coluna para uma das tabelas do AWS Glue. Se todas as tabelas da consulta tiverem estatísticas, o Athena usará as estatísticas para criar um plano de execução que ele determina que terá a melhor performance. O otimizador de consultas calcula planos alternativos com base em um modelo estatístico e depois seleciona o que tem maior probabilidade de executar a consulta em menos tempo. As estatísticas das tabelas do AWS Glue são coletadas e armazenadas no AWS Glue Data Catalog, e disponibilizadas ao Athena para melhorar o planejamento e a execução das consultas. Essas estatísticas são coletadas no nível da coluna, como número de valores distintos, número de valores nulos, máximos e mínimos em tipos de arquivo como Parquet, ORC, JSON, ION, CSV e XML. O Amazon Athena usa essas estatísticas para otimizar as consultas aplicando os filtros mais restritivos no processamento das consultas assim que possível. Essa filtragem limita o uso da memória e o número de registros que devem ser lidos para fornecer os resultados das consultas. Em conjunto com o CBO, o Athena usa um atributo denominado otimizador baseado em regras (RBO). O RBO aplica mecanicamente regras que devem melhorar a performance das consultas. O RBO geralmente é útil porque suas transformações visam simplificar o plano de consulta. Porém, como o RBO não realiza cálculos de custos nem comparações de planos, consultas mais complicadas tornam difícil para o RBO criar um plano ideal. Por isso, o Athena usa ambos o RBO e o CBO para otimizar as consultas. Depois que o Athena identifica as oportunidades de melhorar a execução das consultas, ele cria um plano ideal. Para obter mais informações sobre detalhes do plano de execução, consulte [Visualização de planos de execução para consultas SQL](query-plans.md). Para ver uma discussão detalhada sobre como o CBO funciona, consulte [Speed up queries with the cost-based optimizer in Amazon Athena](https://aws.amazon.com/blogs/big-data/speed-up-queries-with-cost-based-optimizer-in-amazon-athena/) no AWS Big Data. Para gerar estatísticas para tabelas do AWS Glue Catalog, você pode usar o console do Athena, o console do AWS Glue ou as APIs do AWS Glue. Como o Athena é integrado ao AWS Glue Catalog, você obtém automaticamente os aprimoramentos de performance das consultas correspondentes quando executa consultas no Amazon Athena. ## Considerações e limitações + **Tipos de tabela**: atualmente, o atributo CBO do Athena é compatível apenas com as tabelas do Hive e Iceberg que estão no AWS Glue Data Catalog. + **Athena for Spark**: o atributo CBO não está disponível no Athena for Spark. + **Preços**: para obter informações sobre preços, visite a [página de preços do AWS Glue](https://aws.amazon.com/glue/pricing). ## Gerar estatísticas de uma tabela com uso do console do Athena Esta seção descreve como usar o console do Athena para gerar estatísticas no nível da tabela ou da coluna para uma tabela no AWS Glue. Para obter informações sobre o uso do AWS Glue para gerar estatísticas de tabelas, consulte [Working with column statistics](https://docs.aws.amazon.com/glue/latest/dg/column-statistics.html) no *AWS Glue Developer Guide*. **Gerar estatísticas para uma tabela usando o console do Athena** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. Na lista **Tabelas** do editor de consultas do Athena, escolha os três pontos verticais para a tabela que você deseja e depois escolha **Gerar estatísticas.** ![\[Menu de contexto para uma tabela no editor de consultas do Athena.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/cost-based-optimizer-1.png) 1. Na caixa de diálogo **Gerar estatísticas**, escolha **Todas as colunas** para gerar estatísticas para todas as colunas da tabela ou escolha **Colunas selecionadas** para selecionar colunas específicas. **Todas as colunas** é a configuração padrão. ![\[A caixa de diálogo para gerar estatísticas.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/cost-based-optimizer-2.png) 1. Para **perfil do serviço do AWS Glue**, crie ou selecione um perfil de serviço existente para dar permissão ao AWS Glue para gerar estatísticas. O perfil de serviço do AWS Glue também exige permissões de [https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) para o bucket do Amazon S3 que contém os dados da tabela. ![\[Escolher um perfil de serviço do AWS Glue.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/cost-based-optimizer-3.png) 1. Escolha **Gerar estatísticas**. Um banner de notificação **Gerando estatísticas para a *table\$1name*** mostra o status da tarefa. ![\[O banner de notificação Gerando estatísticas.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/cost-based-optimizer-4.png) 1. Para visualizar detalhes no console do AWS Glue, escolha **Visualizar no Glue**. Para obter informações sobre a visualização de estatísticas no console do AWS Glue, consulte [Viewing column statistics](https://docs.aws.amazon.com/glue/latest/dg/view-column-stats.html) no *AWS Glue Developer Guide*. 1. Depois que as estatísticas são geradas, as tabelas e colunas que têm estatísticas trazem a palavra **Estatísticas** entre parênteses, como na imagem a seguir. ![\[Uma tabela mostrando os ícones de estatísticas no editor de consultas do Athena.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/cost-based-optimizer-5.png) Agora, quando você executar consultas, o Athena realizará a otimização baseada em custos nas tabelas e colunas para as quais as estatísticas foram geradas. ## Habilitar e desabilitar estatísticas de tabelas Quando você gera estatísticas para uma tabela Iceberg seguindo as etapas da seção anterior, uma propriedade de tabela do Glue, denominada `use_iceberg_statistics`, é automaticamente adicionada à tabela Iceberg no AWS Glue Data Catalog e definida como **verdadeira** por padrão. Se você remover essa propriedade ou defini-la como **falsa**, o CBO não usará as estatísticas da tabela Iceberg ao tentar otimizar o plano de consultas durante a execução de consultas, mesmo que as estatísticas tenham sido geradas pelo Glue. Para obter mais informações sobre como gerar estatísticas de tabelas, consulte [Gerar estatísticas de uma tabela com uso do console do Athena](#cost-based-optimizer-generating-table-statistics-using-the-athena-console). Por outro lado, as tabelas do Hive no Glue Data Catalog não têm uma propriedade de tabela semelhante para habilitar ou desabilitar o uso de estatísticas de tabelas para o CBO. Como resultado, o CBO sempre usa as estatísticas de tabelas geradas pelo Glue ao tentar otimizar o plano de consultas para tabelas do Hive. ## Recursos adicionais Para mais informações, consulte o recurso a seguir. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/zUHEXJdHUxs?si=rMAhJj3I5IlhN-1R/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/zUHEXJdHUxs?si=rMAhJj3I5IlhN-1R) # Consultar dados do S3 Express One Zone A classe de armazenamento Amazon S3 Express One Zone é uma classe de armazenamento do Amazon S3 com alta performance que fornece tempos de resposta abaixo de dez milissegundos. Dessa forma, essa classe é útil para aplicações que acessam dados frequentemente com centenas de milhares de solicitações por segundo. A classe S3 Express One Zone replica e armazena dados na mesma zona de disponibilidade para otimizar a velocidade e os custos. Isso difere das classes de armazenamento regionais do Amazon S3, que replicam automaticamente os dados em, no mínimo, três zonas de disponibilidade da AWS em uma Região da AWS. Para obter mais informações, consulte [What is S3 Express One Zone?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-one-zone.html) no *Guia do usuário do Amazon S3*. ## Pré-requisitos Confirme se as seguintes condições foram atendidas antes de começar a usar: + **Versão 3 do mecanismo Athena**: para usar a classe S3 Express One Zone com o Athena SQL, o grupo de trabalho deve estar configurado para usar a versão 3 do mecanismo Athena. + **Permissões do S3 Express One Zone**: quando a classe S3 Express One Zone chama uma ação como `GET`, `LIST` ou `PUT` em um objeto do Amazon S3, a classe de armazenamento chama `CreateSession` em seu nome. Por esse motivo, a política do IAM deve permitir a ação `s3express:CreateSession`, que possibilita ao Athena invocar a operação de API correspondente. ## Considerações e limitações Ao consultar a classe S3 Express One Zone com o Athena, considere os pontos apresentados a seguir. + Os buckets do S3 Express One Zone oferecem suporte as criptografias `SSE_S3` e `SSE-KMS`. Os resultados da consulta do Athena são gravados usando a criptografia `SSE_S3`, independentemente da opção escolhida por você nas configurações do grupo de trabalho para criptografar os resultados da consulta. Essa limitação inclui todos os cenários em que o Athena grava dados em buckets da classe S3 Express One Zone, incluindo instruções `CREATE TABLE AS` (CTAS) e `INSERT INTO`. + Não há suporte para o crawler do AWS Glue para a criação de tabelas em dados do S3 Express One Zone. + Não há suporte para a instrução `MSCK REPAIR TABLE`. Como solução alternativa, use [ALTER TABLE ADD PARTITION](alter-table-add-partition.md). + Nenhuma instrução DDL de modificação de tabela para o Apache Iceberg (ou seja, nenhuma instrução `ALTER TABLE`) é compatível com o S3 Express One Zone. + O Lake Formation não é compatível com os buckets do S3 Express One Zone. + Não há suporte ou o suporte é limitado para os formatos de arquivos e de tabelas apresentados a seguir. Se os formatos não estiverem listados, mas forem compatíveis com o Athena (como Parquet, ORC e JSON), eles também terão suporte para uso com o armazenamento do S3 Express One Zone. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/querying-express-one-zone.html) ## Conceitos básicos Consultar dados da classe S3 Express One Zone com o Athena é simples. Para começar a usar, siga o procedimento apresentado a seguir. **Como usar o Athena SQL para consultar dados da classe S3 Express One Zone** 1. Faça a transição dos seus dados para o armazenamento do S3 Express One Zone. Para obter mais informações, consulte [Configurar a classe de armazenamento de um objeto](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-class-intro.html#sc-howtoset) no *Guia do usuário do Amazon S3*. 1. Use uma instrução [CREATE TABLE](create-table.md) no Athena para catalogar seus dados no AWS Glue Data Catalog. Para obter informações sobre como criar tabelas no Athena, consulte [Criar tabelas no Athena](creating-tables.md) e a instrução [CREATE TABLE](create-table.md). 1. (Opcional) Configure a localização do resultado da consulta do grupo de trabalho do Athena para usar um *bucket de diretório* do Amazon S3. Os buckets de diretório do Amazon S3 têm uma performance aprimorada quando comparados aos buckets gerais e são projetados para workloads ou aplicações críticas à performance que requerem latência consistente abaixo de dez milissegundos. Para obter mais informações, consulte [Directory buckets overview](https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-overview.html) no *Guia do usuário do Amazon S3*. # Consultar os objetos restaurados do Amazon Glacier É possível usar o Amazon Athena para consultar os objetos restaurados das [classes de armazenamento do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-class-intro.html#sc-glacier) do Amazon Glacier Flexible Retrieval (antigo Glacier) e do Amazon Glacier Deep Archive. É necessário habilitar esse recurso com base em tabelas. Se você não habilitar o atributo em uma tabela antes de executar a consulta, o Athena ignorará todos os objetos do Amazon Glacier Flexible Retrieval e do Amazon Glacier Deep Archive dessa tabela durante a execução da consulta. ## Condições e limitações + A consulta de objetos restaurados do Amazon Glacier é compatível apenas com a versão 3 do mecanismo do Athena. + O atributo é compatível somente com tabelas do Apache Hive. + É necessário restaurar seus objetos antes de consultar os dados; o Athena não restaura objetos para você. ## Configurar uma tabela para usar objetos restaurados Para configurar sua tabela do Athena de modo a incluir objetos restaurados em suas consultas, é necessário definir a propriedade de tabela `read_restored_glacier_objects` como `true`. Para fazer isso, você pode usar o editor de consultas do Athena ou o console do AWS Glue. Você também pode usar a [CLI do AWS Glue](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/update-table.html), a [API do AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-catalog-tables.html#aws-glue-api-catalog-tables-UpdateTable) ou o [SDK do AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/sdk-general-information-section.html). ### Usar o editor de consultas do Athena No Athena, você pode usar o comando [ALTER TABLE SET TBLPROPERTIES](alter-table-set-tblproperties.md) para definir a propriedade da tabela, como no exemplo a seguir. ``` ALTER TABLE table_name SET TBLPROPERTIES ('read_restored_glacier_objects' = 'true') ``` ### Usar o console do AWS Glue Edite a tabela no console do AWS Glue e realize as seguintes etapas para adicionar a propriedade de tabela `read_restored_glacier_objects`. **Para configurar as propriedades da tabela no console do 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. Execute um destes procedimentos: + Escolha **Ir para catálogo de dados**. + No painel de navegação, escolha **Tabelas do catálogo de dados**. 1. Na página **Tabelas**, na lista de tabelas, escolha o link para a tabela que você deseja editar. 1. Selecione **Actions** (Ações), **Edit** (Editar). 1. Na página **Editar tabela**, na seção **Propriedades da tabela**, adicione o par de chave-valor a seguir. + Em **Chave**, adicione `read_restored_glacier_objects`. + Em **Valor**, insira `true`. 1. Escolha **Salvar**. ### Usar a AWS CLI Na AWS CLI, você pode usar o comando [update-table](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/update-table.html) do AWS Glue e seu argumento `--table-input` para redefinir a tabela e, ao fazer isso, adicionar a propriedade `read_restored_glacier_objects`. No argumento `--table-input`, use a estrutura `Parameters` para especificar a propriedade `read_restored_glacier_objects` e o valor de `true`. O argumento para `--table-input` não deve ter espaços e deve usar barras invertidas como escape das aspas duplas. No exemplo a seguir, substitua *my\$1database* e *my\$1table* pelos nomes de seu banco de dados e tabela. ``` aws glue update-table \ --database-name my_database \ --table-input={\"Name\":\"my_table\",\"Parameters\":{\"read_restored_glacier_objects\":\"true\"}} ``` **Importante** O comando `update-table` do AWS Glue funciona no modo de substituição, o que significa que ele substitui a definição da tabela existente pela nova definição especificada pelo parâmetro `table-input`. Por esse motivo, não se esqueça de especificar também todos os campos que deseja que estejam em sua tabela no parâmetro `table-input` ao adicionar a propriedade `read_restored_glacier_objects`. # Lidar com atualizações de esquemas Esta seção apresenta orientações de como processar as atualizações de esquema nos vários formatos de dados. O Athena é um mecanismo de consulta “schema-on-read”. Isso significa que, quando você cria uma tabela no Athena, ele aplica esquemas durante a leitura dos dados. Ela não altera nem reescrever os dados subjacentes. Se você antecipar alterações nos esquemas de tabela, considere criá-los em um formato de dados adequado para suas necessidades. Seus objetivos são reutilizar as consultas existentes do Athena nos esquemas em desenvolvimento e evitar erros de incompatibilidade de esquemas ao consultar tabelas com partições. Para atingir essas metas, escolha um formato de dados da tabela com base na tabela no seguinte tópico. **Topics** + [Operações de atualização de esquema com suporte por formato de dados](#summary-of-updates) + [Noções básicas do acesso ao índice para Apache ORC e Apache Parquet](#index-access) + [Fazer atualizações de esquema](make-schema-updates.md) + [Atualizar tabelas com partições](updates-and-partitions.md) ## Operações de atualização de esquema com suporte por formato de dados A tabela a seguir resume os formatos de armazenamento físico de dados e os manuseios do esquema com suporte. Use esta tabela para ajudar a escolher o formato que permitirá que você continue usando as consultas do Athena mesmo que seus esquemas sejam alterados ao longo do tempo. Nessa tabela, observe que o Parquet e ORC são formatos de coluna com diferentes métodos de acesso padrão à coluna. Por padrão, o Parquet acessa colunas por nome e o ORC por índice (valor ordinal). Portanto, o Athena oferece uma propriedade SerDe definida no momento da criação de uma tabela para alternar o método de acesso padrão a colunas, o que permite maior flexibilidade com o desenvolvimento do esquema. Para o Parquet, a propriedade `parquet.column.index.access` pode ser definida como `true`, que define que o método de acesso à coluna usará o número ordinal da coluna. Definir essa propriedade como `false` fará com que o método de acesso à coluna use o nome da coluna. Da mesma forma, para ORC, use a propriedade `orc.column.index.access` para controlar o método de acesso à coluna. Para obter mais informações, consulte [Noções básicas do acesso ao índice para Apache ORC e Apache Parquet](#index-access). Os formatos CSV e TSV permitem que você faça todos os manuseios do esquema, exceto a reorganização de colunas ou a adição de colunas ao início da tabela. Por exemplo, se a evolução do seu esquema requer apenas a renomeação de colunas, mas não a remoção delas, você pode optar por criar suas tabelas nos formatos CSV ou TSV. Se você precisar remover colunas, não use os formatos CSV ou TSV. Em vez disso, use qualquer um dos outros formatos compatíveis, de preferência um formato de coluna, como Parquet ou ORC. **Atualizações de esquema e formatos de dados no Athena** | Tipo esperado de atualização de esquema | Resumo | CSV (com e sem cabeçalhos) e TSV | JSON | AVRO | PARQUET: leitura por nome (padrão) | PARQUET: leitura por índice | ORC: leitura por índice (padrão) | ORC: leitura por nome | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | [Renomear colunas](updates-renaming-columns.md) | Armazene seus dados em CSV e TSV, ou em ORC e Parquet se eles são lidos por índice. | S | N | N | N | S | S | N | | [Adicionar colunas no início ou no meio da tabela](updates-add-columns-beginning-middle-of-table.md) | Armazene seus dados em JSON e AVRO, ou em Parquet e ORC se eles são lidos por nome. Não use CSV e TSV. | N | S | S | S | N | N | S | | [Adicionar colunas no final da tabela](updates-add-columns-end-of-table.md) | Armazene seus dados em CSV ou TSV, JSON, AVRO, ORC ou Parquet. | S | S | S | S | S | S | S | | [Remover colunas](updates-removing-columns.md) | Armazene seus dados em JSON e AVRO, ou em Parquet e ORC se eles são lidos por nome. Não use CSV e TSV. | N | S | S | S | N | N | S | | [Reclassificar colunas](updates-reordering-columns.md) | Armazene seus dados em AVRO, JSON ou em Parquet e ORC se eles são lidos por nome. | N | S | S | S | N | N | S | | [Alterar o tipo de dados de uma coluna](updates-changing-column-type.md) | Armazene seus dados em qualquer formato, mas faça o teste da consulta no Athena para garantir que os tipos de dados sejam compatíveis. No Parquet e no ORC, a alteração de um tipo de dados funciona apenas para tabelas particionadas. | S | S | S | S | S | S | S | ## Noções básicas do acesso ao índice para Apache ORC e Apache Parquet PARQUET e ORC são formatos de coluna para armazenamento físico de dados que podem ser lidos por índice ou por nome. O armazenamento dos dados em qualquer um desses formatos permite que você execute todas as operações nos esquemas e execute as consultas do Athena sem erros de incompatibilidade de esquemas. + Por padrão, o Athena *lê o ORC por índice*, conforme definido em `SERDEPROPERTIES ( 'orc.column.index.access'='true')`. Para obter mais informações, consulte [ORC: leitura por índice](#orc-read-by-index). + O Athena lê *Parquet por nome, por padrão*, conforme definido em `SERDEPROPERTIES ( 'parquet.column.index.access'='false')`. Para obter mais informações, consulte [Parquet: leitura por nome](#parquet-read-by-name). Uma vez que essas leituras são padrão, a especificação das propriedades SerDe em suas consultas `CREATE TABLE` é opcional; elas são usadas implicitamente. Quando são usadas, elas permitem que você execute algumas operações de atualização de esquema enquanto impedem outras operações semelhantes. Para habilitar essas operações, execute outra consulta `CREATE TABLE` e altere as configurações SerDe. **nota** As propriedades SerDe *não* são propagadas automaticamente para cada partição. Use instruções `ALTER TABLE ADD PARTITION` para definir as propriedades SerDe para cada partição. Para automatizar esse processo, escreva um script que execute instruções `ALTER TABLE ADD PARTITION`. As seções a seguir descrevem esses casos em detalhes. ### ORC: leitura por índice Uma tabela no formato *ORC é lida por índice*, por padrão. Isso é definido pela seguinte sintaxe: ``` WITH SERDEPROPERTIES ( 'orc.column.index.access'='true') ``` A *leitura por índice* permite renomear colunas. No entanto, não será mais possível remover colunas nem as adicionar no meio da tabela. Para fazer com que o ORC seja lido por nome, o que permitirá que você adicione colunas no meio da tabela ou remova as colunas em ORC, defina a propriedade `orc.column.index.access` do SerDe como `false` na instrução `CREATE TABLE`. Com essa configuração, não será mais possível renomear colunas. **nota** No mecanismo Athena versão 2, quando as tabelas ORC são definidas para serem lidas por nome, o Athena exige que todos os nomes de coluna dos arquivos ORC estejam em letras minúsculas. Como o Apache Spark não usa nomes de campo em letras minúsculas ao gerar arquivos ORC, o Athena talvez não consiga ler os dados que são gerados. A solução alternativa é renomear as colunas usando letras minúsculas ou usar o mecanismo Athena versão 3. O exemplo a seguir ilustra como alterar o ORC para que ele seja lido por nome: ``` CREATE EXTERNAL TABLE orders_orc_read_by_name ( `o_comment` string, `o_orderkey` int, `o_custkey` int, `o_orderpriority` string, `o_orderstatus` string, `o_clerk` string, `o_shippriority` int, `o_orderdate` string ) ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.orc.OrcSerde' WITH SERDEPROPERTIES ( 'orc.column.index.access'='false') STORED AS INPUTFORMAT 'org.apache.hadoop.hive.ql.io.orc.OrcInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.orc.OrcOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/orders_orc/'; ``` ### Parquet: leitura por nome Uma tabela no formato *Parquet é lida por nome*, por padrão. Isso é definido pela seguinte sintaxe: ``` WITH SERDEPROPERTIES ( 'parquet.column.index.access'='false') ``` *A leitura por nome* permite que você remova colunas ou as adicione no meio da tabela. No entanto, não será mais possível renomeá-las. Para fazer com que o Parquet seja lido por índice, o que permitirá que você renomeie colunas, é necessário criar uma tabela com a propriedade `parquet.column.index.access` do SerDe e defini-la como `true`. # Fazer atualizações de esquema Este tópico descreve algumas alterações que você pode fazer no esquema em instruções `CREATE TABLE` sem alterar os dados de fato. Para atualizar um esquema, em alguns casos é possível usar um comando `ALTER TABLE`, mas em outros casos você não modifica uma tabela existente. Em vez disso, você cria uma tabela com um novo nome que modifica o esquema usado na instrução `CREATE TABLE` original. Dependendo de como você espera que seus esquemas evoluam, para continuar usando as consultas do Athena, escolha um formato de dados compatível. Considere uma aplicação que lê informações de pedidos em uma tabela de `orders` que existe em dois formatos: CSV e Parquet. O exemplo a seguir cria uma tabela em Parquet: ``` CREATE EXTERNAL TABLE orders_parquet ( `orderkey` int, `orderstatus` string, `totalprice` double, `orderdate` string, `orderpriority` string, `clerk` string, `shippriority` int ) STORED AS PARQUET LOCATION 's3://amzn-s3-demo-bucket/orders_ parquet/'; ``` O exemplo a seguir cria a mesma tabela em CSV: ``` CREATE EXTERNAL TABLE orders_csv ( `orderkey` int, `orderstatus` string, `totalprice` double, `orderdate` string, `orderpriority` string, `clerk` string, `shippriority` int ) ROW FORMAT DELIMITED FIELDS TERMINATED BY ',' LOCATION 's3://amzn-s3-demo-bucket/orders_csv/'; ``` Os tópicos a seguir mostram como as atualizações nessas tabelas afetam as consultas do Athena. **Topics** + [Adicionar colunas no início ou no meio da tabela](updates-add-columns-beginning-middle-of-table.md) + [Adicionar colunas no final da tabela](updates-add-columns-end-of-table.md) + [Remover colunas](updates-removing-columns.md) + [Renomear colunas](updates-renaming-columns.md) + [Reclassificar colunas](updates-reordering-columns.md) + [Alteração do tipo de dados de uma coluna](updates-changing-column-type.md) # Adicionar colunas no início ou no meio da tabela A adição de colunas é uma das alterações do esquema mais frequentes. Por exemplo, você pode adicionar uma nova coluna para enriquecer a tabela com novos dados. Ou você poderá adicionar uma nova coluna se a origem para uma coluna existente for alterada e manter a versão anterior deste coluna para ajustar os aplicativos que dependem delas. Para adicionar colunas no início ou no meio da tabela e continuar executando consultas em tabelas existentes, use os formatos AVRO e JSON, bem como Parquet e ORC, se a propriedade do SerDe estiver definida para leitura por nome. Para mais informações, consulte [Noções básicas do acesso ao índice para Apache ORC e Apache Parquet](handling-schema-updates-chapter.md#index-access). Não adicione colunas no início ou no meio da tabela em CSV e TSV, pois esses formatos dependem da classificação. Se uma coluna for adicionada em um desses casos, ocorrerá um erro de incompatibilidade de esquema quando o esquema de partições for alterado. O exemplo a seguir cria uma nova tabela que adiciona uma coluna `o_comment` no meio de uma tabela baseada em dados JSON. ``` CREATE EXTERNAL TABLE orders_json_column_addition ( `o_orderkey` int, `o_custkey` int, `o_orderstatus` string, `o_comment` string, `o_totalprice` double, `o_orderdate` string, `o_orderpriority` string, `o_clerk` string, `o_shippriority` int, ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' LOCATION 's3://amzn-s3-demo-bucket/orders_json/'; ``` # Adicionar colunas no final da tabela Se você criar tabelas em qualquer um dos formatos compatíveis com o Athena, como Parquet, ORC, Avro, JSON, CSV e TSV, poderá usar a instrução `ALTER TABLE ADD COLUMNS` para adicionar colunas após as colunas existentes, mas antes das colunas de partição. O exemplo a seguir adiciona uma coluna `comment` no final da tabela `orders_parquet` antes de qualquer coluna de partição: ``` ALTER TABLE orders_parquet ADD COLUMNS (comment string) ``` **nota** Para ver uma nova coluna de tabela no editor de consultas do Athena depois de executar `ALTER TABLE ADD COLUMNS`, atualize manualmente a lista de tabelas no editor e expanda a tabela outra vez. # Remover colunas Talvez você precise remover colunas de tabelas se elas não contiverem dados ou restringir o acesso aos dados contidos nelas. + Você pode remover colunas de tabelas em JSON, Avro e em ORC e Parquet se elas forem lidas por nome. Para mais informações, consulte [Noções básicas do acesso ao índice para Apache ORC e Apache Parquet](handling-schema-updates-chapter.md#index-access). + Não é recomendável remover colunas das tabelas em CSV e TSV se você deseja reter as tabelas que criou no Athena. A remoção de uma coluna rompe o esquema e requer que você recrie a tabela sem a coluna removida. Neste exemplo, remova uma coluna ``totalprice`` de uma tabela em Parquet e execute uma consulta. No Athena, por padrão o Parquet é lido por nome. É por esse motivo que omitimos a configuração SERDEPROPERTIES que especifica a leitura por nome. Observe que a consulta a seguir é bem-sucedida, mesmo que você altere o esquema: ``` CREATE EXTERNAL TABLE orders_parquet_column_removed ( `o_orderkey` int, `o_custkey` int, `o_orderstatus` string, `o_orderdate` string, `o_orderpriority` string, `o_clerk` string, `o_shippriority` int, `o_comment` string ) STORED AS PARQUET LOCATION 's3://amzn-s3-demo-bucket/orders_parquet/'; ``` # Renomear colunas Talvez você queira renomear colunas em suas tabelas para corrigir ortografia, tornar os nomes das colunas mais descritivos ou reutilizar uma coluna existente para evitar a reclassificação dela. Você pode renomear colunas se armazenar seus dados em CSV e TSV, ou em Parquet e ORC, que são configurados para leitura por índice. Para mais informações, consulte [Noções básicas do acesso ao índice para Apache ORC e Apache Parquet](handling-schema-updates-chapter.md#index-access). O Athena lê os dados em CSV e TSV na ordem das colunas no esquema e os retorna na mesma ordem. Ele não usa os nomes de coluna para mapear os dados para uma coluna. É por esse motivo que você pode renomear as colunas em CSV ou TSV sem interromper as consultas do Athena. Uma estratégia para renomear colunas é criar uma tabela com base nos mesmos dados subjacentes, mas usando novos nomes de coluna. O exemplo a seguir cria uma tabela `orders_parquet` chamada `orders_parquet_column_renamed`. O exemplo altera o nome da coluna ``o_totalprice`` para ``o_total_price`` e executa uma consulta no Athena: ``` CREATE EXTERNAL TABLE orders_parquet_column_renamed ( `o_orderkey` int, `o_custkey` int, `o_orderstatus` string, `o_total_price` double, `o_orderdate` string, `o_orderpriority` string, `o_clerk` string, `o_shippriority` int, `o_comment` string ) STORED AS PARQUET LOCATION 's3://amzn-s3-demo-bucket/orders_parquet/'; ``` No caso da tabela do Parquet, a consulta a seguir é executada. No entanto, a coluna renomeada não exibe dados, porque ela estava sendo acessada por nome (um padrão no Parquet) em vez de por índice: ``` SELECT * FROM orders_parquet_column_renamed; ``` Uma consulta com uma tabela em CSV tem aparência semelhante: ``` CREATE EXTERNAL TABLE orders_csv_column_renamed ( `o_orderkey` int, `o_custkey` int, `o_orderstatus` string, `o_total_price` double, `o_orderdate` string, `o_orderpriority` string, `o_clerk` string, `o_shippriority` int, `o_comment` string ) ROW FORMAT DELIMITED FIELDS TERMINATED BY ',' LOCATION 's3://amzn-s3-demo-bucket/orders_csv/'; ``` No caso da tabela CSV, a consulta a seguir é executada, e os dados são exibidos em todas as colunas, incluindo aquela que foi renomeada: ``` SELECT * FROM orders_csv_column_renamed; ``` # Reclassificar colunas Você pode reordenar colunas apenas em tabelas com dados em formatos de leitura por nome, como JSON ou Parquet, que leem por nome, por padrão. Você também pode fazer com que o ORC leia por nome, se necessário. Para mais informações, consulte [Noções básicas do acesso ao índice para Apache ORC e Apache Parquet](handling-schema-updates-chapter.md#index-access). O exemplo a seguir cria uma tabela com as colunas em uma ordem diferente: ``` CREATE EXTERNAL TABLE orders_parquet_columns_reordered ( `o_comment` string, `o_orderkey` int, `o_custkey` int, `o_orderpriority` string, `o_orderstatus` string, `o_clerk` string, `o_shippriority` int, `o_orderdate` string ) STORED AS PARQUET LOCATION 's3://amzn-s3-demo-bucket/orders_parquet/'; ``` # Alteração do tipo de dados de uma coluna Convém usar outro tipo de coluna quando o tipo existente não puder mais conter a quantidade de informações necessárias. Por exemplo, os valores de uma coluna de ID podem exceder o tamanho do tipo de dados `INT` e exigir o uso do tipo de dados `BIGINT`. ## Considerações Ao planejar usar um tipo de dados diferente para uma coluna, leve em consideração os seguintes pontos: + Na maioria dos casos, você não pode alterar diretamente o tipo de dados de uma coluna. Em vez disso, você recria a tabela do Athena e define a coluna com o novo tipo de dados. + Apenas certos tipos de dados podem ser lidos como outros tipos de dados. Consulte a tabela nesta seção para ver os tipos de dados que podem ser tratados dessa forma. + Para dados em formato Parquet e ORC, você não pode usar um tipo de dados diferente para uma coluna se a tabela não estiver particionada. + Para tabelas particionadas no Parquet e no ORC, o tipo de coluna de uma partição pode ser diferente do tipo de coluna de outra partição, e o Athena aplicará `CAST` ao tipo desejado, se possível. Para mais informações, consulte [Evitar erros de não correspondência de esquema para tabelas com partições](updates-and-partitions.md#partitions-dealing-with-schema-mismatch-errors). + Para tabelas criadas usando o [LazySimpleSerDe](lazy-simple-serde.md) apenas, é possível usar a declaração `ALTER TABLE REPLACE COLUMNS` para substituir colunas existentes por um tipo de dados diferente, mas todas as colunas existentes que você deseja manter também devem ser redefinidas na declaração, caso contrário, elas serão excluídas. Para obter mais informações, consulte [ALTER TABLE REPLACE COLUMNS](alter-table-replace-columns.md). + Para tabelas Apache Iceberg apenas, você pode usar a declaração [ALTER TABLE CHANGE COLUMN](querying-iceberg-alter-table-change-column.md) para alterar o tipo de dados de uma coluna. A declaração `ALTER TABLE REPLACE COLUMNS` não é suportada para tabelas Iceberg. Para obter mais informações, consulte [Evoluir o esquema de tabelas do Iceberg](querying-iceberg-evolving-table-schema.md). **Importante** É altamente recomendável testar e verificar suas consultas antes de executar as conversões de tipo de dados. Se o Athena não puder usar o tipo de dados de destino, a consulta `CREATE TABLE` poderá falhar. ## Usar tipos de dados compatíveis Sempre que possível, use tipos de dados compatíveis. A tabela a seguir lista os tipos de dados que podem ser tratados como outros tipos de dados: | Tipos de dados originais | Tipos de dados de destino disponíveis | | --- | --- | | STRING | BYTE, TINYINT, SMALLINT, INT, BIGINT | | BYTE | TINYINT, SMALLINT, INT, BIGINT | | TINYINT | SMALLINT, INT, BIGINT | | SMALLINT | INT, BIGINT | | INT | BIGINT | | FLOAT | DOUBLE | O exemplo a seguir usa a instrução `CREATE TABLE` da tabela `orders_json` original para criar uma nova tabela chamada `orders_json_bigint`. A nova tabela usa `BIGINT` em vez de `INT` como tipo de dados para a coluna ``o_shippriority``. ``` CREATE EXTERNAL TABLE orders_json_bigint ( `o_orderkey` int, `o_custkey` int, `o_orderstatus` string, `o_totalprice` double, `o_orderdate` string, `o_orderpriority` string, `o_clerk` string, `o_shippriority` BIGINT ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' LOCATION 's3://amzn-s3-demo-bucket/orders_json'; ``` A seguinte consulta é executada com êxito, semelhante à consulta `SELECT` original, antes que o tipo de dados seja alterado: ``` Select * from orders_json LIMIT 10; ``` # Atualizar tabelas com partições No Athena, uma tabela e suas partições devem usar os mesmos formatos de dados, mas os esquemas podem ser diferentes. Quando você cria uma nova partição, essa partição geralmente herda o esquema da tabela. Com o passar do tempo, os esquemas podem começar a ser diferentes. Os motivos para isso incluem: + Se o esquema da tabela é alterado, os esquemas para as partições não são atualizados para permanecer em sincronia com o esquema da tabela. + O Crawler do AWS Glue permite que você descubra dados em partições com esquemas diferentes. Isso significa que, se você criar uma tabela no Athena com o AWS Glue, depois que o crawler concluir o processamento, os esquemas da tabela e suas partições poderão ser diferentes. + Se você adicionar partições diretamente usando uma API da AWS. O Athena processará tabelas com partições com êxito se elas estiverem de acordo com as restrições a seguir. Se essas restrições não forem atendidas, o Athena emitirá um erro HIVE\$1PARTITION\$1SCHEMA\$1MISMATCH. + Cada esquema de partição é compatível com o esquema da tabela. + O formato de dados da tabela permite o tipo de atualização que você deseja executar: adicionar, excluir, reclassificar colunas ou alterar um tipo de dados da coluna. Por exemplo, para os formatos CSV e TSV, você pode renomear colunas, adicionar novas colunas no final da tabela e alterar o tipo de dados de uma coluna se os tipos forem compatíveis, mas você não pode remover colunas. Para outros formatos, você pode adicionar ou remover colunas ou alterar o tipo de dados de uma coluna para outro se os tipos forem compatíveis. Para obter informações, consulte [Resumo: atualizações e formatos de dados no Athena](handling-schema-updates-chapter.md#summary-of-updates). ## Evitar erros de não correspondência de esquema para tabelas com partições No início da execução da consulta, o Athena verifica o esquema da tabela confirmando se cada tipo de dados da coluna é compatível entre a tabela e a partição. + Para os tipos de armazenamento de dados ORC e Parquet, o Athena usa os nomes das colunas para a verificação de esquema com base no nome da coluna. Isso elimina erros `HIVE_PARTITION_SCHEMA_MISMATCH` nas tabelas com partições nos tipos Parquet e ORC. (Isso será verdadeiro no ORC se a propriedade SerDe for definida para acessar o índice por nome: `orc.column.index.access=FALSE`. Por padrão, o Parquet lê o índice por nome). + Para CSV, JSON e AVRO, o Athena usa uma verificação de esquema com base no índice. Isso significa que, se você encontrar um erro de incompatibilidade de esquema, deverá descartar a partição que está causando essa incompatibilidade e recriá-la, de modo que o Athena possa consultá-la sem falhas. O Athena compara o esquema da tabela com os esquemas da partição. Se você criar uma tabela em CSV, JSON e AVRO no Athena com o crawler do AWS Glue, depois que o crawler concluir o processamento, os esquemas da tabela e suas partições poderão ser diferentes. Se houver incompatibilidade entre os esquemas da tabela e da partição, haverá falha nas consultas no Athena devido a um erro de verificação de esquema semelhante a este: 'crawler\$1test.click\$1avro' is declared as type 'string', but partition 'partition\$10=2017-01-17' declared column 'col68' as type 'double'. Uma solução comum para esses erros é eliminar a partição que está causando o erro e recriá-la. Para obter mais informações, consulte [ALTER TABLE DROP PARTITION](alter-table-drop-partition.md) e [ALTER TABLE ADD PARTITION](alter-table-add-partition.md). # Consultar matrizes O Amazon Athena permite criar arrays, concatená-los, convertê-los em tipos de dados diferentes e filtrá-los, nivelá-los e classificá-los. **Topics** + [Criar matrizes](creating-arrays.md) + [Concatenar strings e matrizes](concatenating-strings-and-arrays.md) + [Converter tipos de dados de matriz](converting-array-data-types.md) + [Descobrir tamanhos de matrizes](finding-lengths.md) + [Acessar elementos de matrizes](accessing-array-elements.md) + [Nivelar matrizes aninhadas](flattening-arrays.md) + [Criar matrizes a partir de subconsultas](creating-arrays-from-subqueries.md) + [Filtrar matrizes](filtering-arrays.md) + [Classificar matrizes](sorting-arrays.md) + [Usar funções de agregação com matrizes](arrays-and-aggregation.md) + [Converter matrizes em strings](converting-arrays-to-strings.md) + [Usar matrizes para criar mapas](arrays-create-maps.md) + [Consultar matrizes de tipos complexos](rows-and-structs.md) # Criar matrizes Para criar um literal de array no Athena, use a palavra-chave `ARRAY` seguida por colchetes `[ ]` e inclua os elementos do array separados por vírgulas. ## Exemplos Essa consulta cria uma matriz com quatro elementos. ``` SELECT ARRAY [1,2,3,4] AS items ``` Ela retorna: ``` +-----------+ | items | +-----------+ | [1,2,3,4] | +-----------+ ``` Essa consulta cria duas matrizes. ``` SELECT ARRAY[ ARRAY[1,2], ARRAY[3,4] ] AS items ``` Ela retorna: ``` +--------------------+ | items | +--------------------+ | [[1, 2], [3, 4]] | +--------------------+ ``` Para criar uma matriz com base em colunas selecionadas de tipos compatíveis, use uma consulta, como neste exemplo: ``` WITH dataset AS ( SELECT 1 AS x, 2 AS y, 3 AS z ) SELECT ARRAY [x,y,z] AS items FROM dataset ``` Essa consulta retorna: ``` +-----------+ | items | +-----------+ | [1,2,3] | +-----------+ ``` No exemplo a seguir, duas matrizes são selecionadas e retornadas como uma mensagem de boas-vindas. ``` WITH dataset AS ( SELECT ARRAY ['hello', 'amazon', 'athena'] AS words, ARRAY ['hi', 'alexa'] AS alexa ) SELECT ARRAY[words, alexa] AS welcome_msg FROM dataset ``` Essa consulta retorna: ``` +----------------------------------------+ | welcome_msg | +----------------------------------------+ | [[hello, amazon, athena], [hi, alexa]] | +----------------------------------------+ ``` Para criar uma matriz de pares chave/valor, use o operador `MAP` que utiliza uma matriz de chaves seguida de uma matriz de valores, como neste exemplo: ``` SELECT ARRAY[ MAP(ARRAY['first', 'last', 'age'],ARRAY['Bob', 'Smith', '40']), MAP(ARRAY['first', 'last', 'age'],ARRAY['Jane', 'Doe', '30']), MAP(ARRAY['first', 'last', 'age'],ARRAY['Billy', 'Smith', '8']) ] AS people ``` Essa consulta retorna: ``` +-----------------------------------------------------------------------------------------------------+ | people | +-----------------------------------------------------------------------------------------------------+ | [{last=Smith, first=Bob, age=40}, {last=Doe, first=Jane, age=30}, {last=Smith, first=Billy, age=8}] | +-----------------------------------------------------------------------------------------------------+ ``` # Concatenar strings e matrizes A concatenação de strings e a concatenação de matrizes usam técnicas semelhantes. ## Concatenar strings Para concatenar duas strings, você pode usar o operador de barra dupla `||`, como no exemplo a seguir. ``` SELECT 'This' || ' is' || ' a' || ' test.' AS Concatenated_String ``` Essa consulta retorna: **** | \$1 | Concatenated\$1String | | --- | --- | | 1 | `This is a test.` | Você pode usar a função `concat()` para obter o mesmo resultado. ``` SELECT concat('This', ' is', ' a', ' test.') AS Concatenated_String ``` Essa consulta retorna: **** | \$1 | Concatenated\$1String | | --- | --- | | 1 | `This is a test.` | Você pode usar a função `concat_ws()` para concatenar strings com o separador especificado no primeiro argumento. ``` SELECT concat_ws(' ', 'This', 'is', 'a', 'test.') as Concatenated_String ``` Essa consulta retorna: **** | \$1 | Concatenated\$1String | | --- | --- | | 1 | `This is a test.` | Para concatenar duas colunas do tipo de dados string usando um ponto, referencie as duas colunas usando aspas duplas e coloque o ponto entre aspas simples como uma string com codificação rígida. Se uma coluna não for do tipo de dados string, você poderá usar `CAST("column_name" as VARCHAR)` para converter a coluna primeiro. ``` SELECT "col1" || '.' || "col2" as Concatenated_String FROM my_table ``` Essa consulta retorna: **** | \$1 | Concatenated\$1String | | --- | --- | | 1 | `col1_string_value.col2_string_value` | ## Concatenar matrizes Você pode usar as mesmas técnicas para concatenar arrays. Para concatenar vários arrays, use o operador de barra dupla `||`. ``` SELECT ARRAY [4,5] || ARRAY[ ARRAY[1,2], ARRAY[3,4] ] AS items ``` Essa consulta retorna: **** | \$1 | itens | | --- | --- | | 1 | `[[4, 5], [1, 2], [3, 4]]` | Para combinar vários arrays em um só, use o operador de barra dupla ou a função `concat()`. ``` WITH dataset AS ( SELECT ARRAY ['Hello', 'Amazon', 'Athena'] AS words, ARRAY ['Hi', 'Alexa'] AS alexa ) SELECT concat(words, alexa) AS welcome_msg FROM dataset ``` Essa consulta retorna: **** | \$1 | welcome\$1msg | | --- | --- | | 1 | `[Hello, Amazon, Athena, Hi, Alexa]` | Para obter mais informações sobre o uso de `concat()` em outras funções de string, consulte [String functions and operators](https://trino.io/docs/current/functions/string.html) (Funções e operadores de string) na documentação do Trino. # Converter tipos de dados de matriz Para converter os dados dos arrays em tipos de dados compatíveis, use o operador `CAST`, como `CAST(value AS type)`. O Athena aceita todos os tipos de dados nativos do Presto. ``` SELECT ARRAY [CAST(4 AS VARCHAR), CAST(5 AS VARCHAR)] AS items ``` Essa consulta retorna: ``` +-------+ | items | +-------+ | [4,5] | +-------+ ``` Crie duas matrizes com elementos de par chave/valor, converta-as em JSON e concatene, como neste exemplo: ``` SELECT ARRAY[CAST(MAP(ARRAY['a1', 'a2', 'a3'], ARRAY[1, 2, 3]) AS JSON)] || ARRAY[CAST(MAP(ARRAY['b1', 'b2', 'b3'], ARRAY[4, 5, 6]) AS JSON)] AS items ``` Essa consulta retorna: ``` +--------------------------------------------------+ | items | +--------------------------------------------------+ | [{"a1":1,"a2":2,"a3":3}, {"b1":4,"b2":5,"b3":6}] | +--------------------------------------------------+ ``` # Descobrir tamanhos de matrizes A função `cardinality` retorna o tamanho de uma matriz, como neste exemplo: ``` SELECT cardinality(ARRAY[1,2,3,4]) AS item_count ``` Essa consulta retorna: ``` +------------+ | item_count | +------------+ | 4 | +------------+ ``` # Acessar elementos de matrizes Para acessar elementos de matriz, use o operador `[]`, com 1 especificando o primeiro elemento, 2 especificando o segundo elemento e assim por diante, como neste exemplo: ``` WITH dataset AS ( SELECT ARRAY[CAST(MAP(ARRAY['a1', 'a2', 'a3'], ARRAY[1, 2, 3]) AS JSON)] || ARRAY[CAST(MAP(ARRAY['b1', 'b2', 'b3'], ARRAY[4, 5, 6]) AS JSON)] AS items ) SELECT items[1] AS item FROM dataset ``` Essa consulta retorna: ``` +------------------------+ | item | +------------------------+ | {"a1":1,"a2":2,"a3":3} | +------------------------+ ``` Para acessar os elementos de uma matriz em uma determinada posição (conhecida como a posição de índice), use a função `element_at()` e especifique o nome da matriz e a posição de índice: + Se o índice for maior que 0, `element_at()` retornará o elemento especificado por você, contando do início ao fim da matriz. Ele se comporta como o operador `[]`. + Se o índice for menor que 0, `element_at()` retornará o elemento, contando do fim ao início da matriz. A consulta a seguir cria uma matriz `words`e seleciona o primeiro elemento `hello` dela como o `first_word`, o segundo elemento `amazon` (contagem a partir do final da matriz) como o `middle_word` e o terceiro elemento `athena` como o `last_word`. ``` WITH dataset AS ( SELECT ARRAY ['hello', 'amazon', 'athena'] AS words ) SELECT element_at(words, 1) AS first_word, element_at(words, -2) AS middle_word, element_at(words, cardinality(words)) AS last_word FROM dataset ``` Essa consulta retorna: ``` +----------------------------------------+ | first_word | middle_word | last_word | +----------------------------------------+ | hello | amazon | athena | +----------------------------------------+ ``` # Nivelar matrizes aninhadas Ao trabalhar com matrizes aninhadas, você normalmente precisa expandir elementos de matriz aninhados para uma única matriz ou expandir a matriz para várias linhas. ## Usar a função de nivelamento Para nivelar elementos de uma matriz aninhada em uma única matriz de valores, use a função `flatten`. Essa consulta retorna uma linha para cada elemento na matriz. ``` SELECT flatten(ARRAY[ ARRAY[1,2], ARRAY[3,4] ]) AS items ``` Essa consulta retorna: ``` +-----------+ | items | +-----------+ | [1,2,3,4] | +-----------+ ``` ## Usar CROSS JOIN e UNNEST Para nivelar uma matriz em várias linhas, use `CROSS JOIN` com o operador `UNNEST`, como neste exemplo: ``` WITH dataset AS ( SELECT 'engineering' as department, ARRAY['Sharon', 'John', 'Bob', 'Sally'] as users ) SELECT department, names FROM dataset CROSS JOIN UNNEST(users) as t(names) ``` Essa consulta retorna: ``` +----------------------+ | department | names | +----------------------+ | engineering | Sharon | +----------------------| | engineering | John | +----------------------| | engineering | Bob | +----------------------| | engineering | Sally | +----------------------+ ``` Para nivelar uma matriz de pares chave/valor, transpor chaves selecionadas para colunas, como neste exemplo: ``` WITH dataset AS ( SELECT 'engineering' as department, ARRAY[ MAP(ARRAY['first', 'last', 'age'],ARRAY['Bob', 'Smith', '40']), MAP(ARRAY['first', 'last', 'age'],ARRAY['Jane', 'Doe', '30']), MAP(ARRAY['first', 'last', 'age'],ARRAY['Billy', 'Smith', '8']) ] AS people ) SELECT names['first'] AS first_name, names['last'] AS last_name, department FROM dataset CROSS JOIN UNNEST(people) AS t(names) ``` Essa consulta retorna: ``` +--------------------------------------+ | first_name | last_name | department | +--------------------------------------+ | Bob | Smith | engineering | | Jane | Doe | engineering | | Billy | Smith | engineering | +--------------------------------------+ ``` Em uma lista de funcionários, selecione o funcionário com a maior pontuação combinada. `UNNEST` pode ser usado na cláusula `FROM` sem um `CROSS JOIN` anterior pois ele é o operador de junção padrão e, portanto, implícito. ``` WITH dataset AS ( SELECT ARRAY[ CAST(ROW('Sally', 'engineering', ARRAY[1,2,3,4]) AS ROW(name VARCHAR, department VARCHAR, scores ARRAY(INTEGER))), CAST(ROW('John', 'finance', ARRAY[7,8,9]) AS ROW(name VARCHAR, department VARCHAR, scores ARRAY(INTEGER))), CAST(ROW('Amy', 'devops', ARRAY[12,13,14,15]) AS ROW(name VARCHAR, department VARCHAR, scores ARRAY(INTEGER))) ] AS users ), users AS ( SELECT person, score FROM dataset, UNNEST(dataset.users) AS t(person), UNNEST(person.scores) AS t(score) ) SELECT person.name, person.department, SUM(score) AS total_score FROM users GROUP BY (person.name, person.department) ORDER BY (total_score) DESC LIMIT 1 ``` Essa consulta retorna: ``` +---------------------------------+ | name | department | total_score | +---------------------------------+ | Amy | devops | 54 | +---------------------------------+ ``` Em uma lista de funcionários, selecione o funcionário com a pontuação individual mais alta. ``` WITH dataset AS ( SELECT ARRAY[ CAST(ROW('Sally', 'engineering', ARRAY[1,2,3,4]) AS ROW(name VARCHAR, department VARCHAR, scores ARRAY(INTEGER))), CAST(ROW('John', 'finance', ARRAY[7,8,9]) AS ROW(name VARCHAR, department VARCHAR, scores ARRAY(INTEGER))), CAST(ROW('Amy', 'devops', ARRAY[12,13,14,15]) AS ROW(name VARCHAR, department VARCHAR, scores ARRAY(INTEGER))) ] AS users ), users AS ( SELECT person, score FROM dataset, UNNEST(dataset.users) AS t(person), UNNEST(person.scores) AS t(score) ) SELECT person.name, score FROM users ORDER BY (score) DESC LIMIT 1 ``` Essa consulta retorna: ``` +--------------+ | name | score | +--------------+ | Amy | 15 | +--------------+ ``` ### Considerações sobre CROSS JOIN e UNNEST Se a função `UNNEST` for usada em uma ou mais matrizes na consulta e uma das matrizes for `NULL`, a consulta não retornará nenhuma linha. Se a função `UNNEST` for usada em uma matriz que é uma string vazia, a string vazia será retornada. Por exemplo, na consulta apresentada a seguir, como a segunda matriz é nula, a consulta não retorna nenhuma linha. ``` SELECT col1, col2 FROM UNNEST (ARRAY ['apples','oranges','lemons']) AS t(col1) CROSS JOIN UNNEST (ARRAY []) AS t(col2) ``` No próximo exemplo, a segunda matriz foi modificada para conter uma string vazia. Para cada linha, a consulta retorna o valor em `col1` e uma string vazia para o valor em `col2`. A string vazia na segunda matriz é necessária para que os valores na primeira matriz sejam retornados. ``` SELECT col1, col2 FROM UNNEST (ARRAY ['apples','oranges','lemons']) AS t(col1) CROSS JOIN UNNEST (ARRAY ['']) AS t(col2) ``` # Criar matrizes a partir de subconsultas Crie uma matriz com base em uma coleção de filas. ``` WITH dataset AS ( SELECT ARRAY[1,2,3,4,5] AS items ) SELECT array_agg(i) AS array_items FROM dataset CROSS JOIN UNNEST(items) AS t(i) ``` Essa consulta retorna: ``` +-----------------+ | array_items | +-----------------+ | [1, 2, 3, 4, 5] | +-----------------+ ``` Para criar um conjunto de valores exclusivos com base em um conjunto de linhas, use a palavra-chave `distinct`. ``` WITH dataset AS ( SELECT ARRAY [1,2,2,3,3,4,5] AS items ) SELECT array_agg(distinct i) AS array_items FROM dataset CROSS JOIN UNNEST(items) AS t(i) ``` Essa consulta retorna o resultado a seguir. Observe que a ordem não é garantida. ``` +-----------------+ | array_items | +-----------------+ | [1, 2, 3, 4, 5] | +-----------------+ ``` Para obter mais informações sobre como usar a função `array_agg`, consulte [Funções aggregate](https://trino.io/docs/current/functions/aggregate.html) na documentação do Trino. # Filtrar matrizes Crie uma matriz com base em uma coleção de filas caso elas correspondam aos critérios de filtro. ``` WITH dataset AS ( SELECT ARRAY[1,2,3,4,5] AS items ) SELECT array_agg(i) AS array_items FROM dataset CROSS JOIN UNNEST(items) AS t(i) WHERE i > 3 ``` Essa consulta retorna: ``` +-------------+ | array_items | +-------------+ | [4, 5] | +-------------+ ``` Filtrar uma matriz com base em se um dos elementos contêm um valor específico, como 2, como neste exemplo: ``` WITH dataset AS ( SELECT ARRAY [ ARRAY[1,2,3,4], ARRAY[5,6,7,8], ARRAY[9,0] ] AS items ) SELECT i AS array_items FROM dataset CROSS JOIN UNNEST(items) AS t(i) WHERE contains(i, 2) ``` Essa consulta retorna: ``` +--------------+ | array_items | +--------------+ | [1, 2, 3, 4] | +--------------+ ``` ## Uso a função `filter` ``` filter(ARRAY [list_of_values], boolean_function) ``` É possível utilizar a função `filter` em uma expressão `ARRAY` para criar um novo array que é o subconjunto dos itens na *list\$1of\$1values* cuja *boolean\$1function* é true. A função `filter` pode ser útil em casos nos quais não é possível usar a função *UNNEST*. O exemplo a seguir filtra valores maiores que zero no array `[1,0,5,-1]`. ``` SELECT filter(ARRAY [1,0,5,-1], x -> x>0) ``` **Resultados** `[1,5]` O exemplo a seguir filtra valores não nulos no array `[-1, NULL, 10, NULL]`. ``` SELECT filter(ARRAY [-1, NULL, 10, NULL], q -> q IS NOT NULL) ``` **Resultados** `[-1,10]` # Classificar matrizes Para criar um array classificado de valores exclusivos com base em um conjunto de linhas, você pode usar a função [array\$1sort](https://prestodb.io/docs/current/functions/array.html#array_sort), como no exemplo a seguir. ``` WITH dataset AS ( SELECT ARRAY[3,1,2,5,2,3,6,3,4,5] AS items ) SELECT array_sort(array_agg(distinct i)) AS array_items FROM dataset CROSS JOIN UNNEST(items) AS t(i) ``` Essa consulta retorna: ``` +--------------------+ | array_items | +--------------------+ | [1, 2, 3, 4, 5, 6] | +--------------------+ ``` Para obter informações sobre como expandir uma matriz em várias linhas, consulte [Nivelar matrizes aninhadas](flattening-arrays.md). # Usar funções de agregação com matrizes + Para adicionar valores dentro de uma matriz, use `SUM`, como no exemplo a seguir. + Para agregar várias linhas dentro de uma matriz, use `array_agg`. Para ter mais informações, consulte [Criar matrizes a partir de subconsultas](creating-arrays-from-subqueries.md). **nota** Desde o mecanismo do Athena versão 2, `ORDER BY` é permitido em funções de agregação. ``` WITH dataset AS ( SELECT ARRAY [ ARRAY[1,2,3,4], ARRAY[5,6,7,8], ARRAY[9,0] ] AS items ), item AS ( SELECT i AS array_items FROM dataset, UNNEST(items) AS t(i) ) SELECT array_items, sum(val) AS total FROM item, UNNEST(array_items) AS t(val) GROUP BY array_items; ``` Na última instrução do `SELECT`, em vez de usar `sum()` e `UNNEST`, você pode usar `reduce()` para reduzir o tempo de processamento e a transferência de dados, como no exemplo a seguir. ``` WITH dataset AS ( SELECT ARRAY [ ARRAY[1,2,3,4], ARRAY[5,6,7,8], ARRAY[9,0] ] AS items ), item AS ( SELECT i AS array_items FROM dataset, UNNEST(items) AS t(i) ) SELECT array_items, reduce(array_items, 0 , (s, x) -> s + x, s -> s) AS total FROM item; ``` As consultas retornam os seguintes resultados. A ordem de resultados obtidos não é garantida. ``` +----------------------+ | array_items | total | +----------------------+ | [1, 2, 3, 4] | 10 | | [5, 6, 7, 8] | 26 | | [9, 0] | 9 | +----------------------+ ``` # Converter matrizes em strings Para converter uma matriz em uma string única, use a função `array_join`. O exemplo independente a seguir cria uma tabela chamada `dataset` que contém um array de alias chamado `words`. A consulta usa `array_join` para unir os elementos do array em `words`, separá-los com espaços e retornar a string resultante em uma coluna de alias chamada `welcome_msg`. ``` WITH dataset AS ( SELECT ARRAY ['hello', 'amazon', 'athena'] AS words ) SELECT array_join(words, ' ') AS welcome_msg FROM dataset ``` Essa consulta retorna: ``` +---------------------+ | welcome_msg | +---------------------+ | hello amazon athena | +---------------------+ ``` # Usar matrizes para criar mapas Os mapas são pares de chave-valor que consistem nos tipos de dados disponíveis no Athena. Para criar mapas, use o operador `MAP` e passe duas matrizes: a primeira é de nomes de coluna (chave) e a segunda é de valores. Todos os valores nas matrizes devem ser do mesmo tipo. Se qualquer um dos elementos de matriz de valor de mapa precisar ser de tipos diferentes, você poderá convertê-los depois. ## Exemplos Este exemplo seleciona um usuário em um conjunto de dados. Ele usa o operador `MAP` e passa duas matrizes. A primeira matriz inclui valores para nomes de coluna, como "primeiro", "último" e "idade". A segunda matriz consiste em valores para cada uma dessas colunas, como "Bob", "Smith", "35". ``` WITH dataset AS ( SELECT MAP( ARRAY['first', 'last', 'age'], ARRAY['Bob', 'Smith', '35'] ) AS user ) SELECT user FROM dataset ``` Essa consulta retorna: ``` +---------------------------------+ | user | +---------------------------------+ | {last=Smith, first=Bob, age=35} | +---------------------------------+ ``` Você pode recuperar valores `Map` selecionando o nome do campo seguido de `[key_name]`, como neste exemplo: ``` WITH dataset AS ( SELECT MAP( ARRAY['first', 'last', 'age'], ARRAY['Bob', 'Smith', '35'] ) AS user ) SELECT user['first'] AS first_name FROM dataset ``` Essa consulta retorna: ``` +------------+ | first_name | +------------+ | Bob | +------------+ ``` # Consultar matrizes de tipos complexos e estruturas aninhadas Os dados de origem normalmente contêm matrizes com tipos de dados complexos e estruturas aninhadas. Os exemplos nesta seção mostram como alterar o tipo de dados do elemento, localizar elementos em arrays e encontrar palavras-chave usando as consultas do Athena. **Topics** + [Crie um `ROW`](creating-row.md) + [Alterar nomes de campo em matrizes com uso de `CAST`](changing-row-arrays-with-cast.md) + [Filtrar matrizes com uso da notação `.`](filtering-with-dot.md) + [Filtrar matrizes com valores aninhados](filtering-nested-with-dot.md) + [Filtrar matrizes com uso de `UNNEST`](filtering-with-unnest.md) + [Localizar palavras-chave em matrizes usando `regexp_like`](filtering-with-regexp.md) # Crie um `ROW` **nota** Os exemplos neste seção usam `ROW` como um meio para criar dados de exemplo com os quais trabalhar. Ao consultar tabelas no Athena, você não precisa criar tipos de dados `ROW` porque eles já foram criados da sua origem dos dados. Quando você usa `CREATE_TABLE`, o Athena define um `STRUCT` nele, preenche-o com dados e cria o tipo de dados `ROW` para cada linha no conjunto de dados. O tipo de dados `ROW` subjacente consiste em campos nomeados de todos os tipos de dados SQL compatíveis. ``` WITH dataset AS ( SELECT ROW('Bob', 38) AS users ) SELECT * FROM dataset ``` Essa consulta retorna: ``` +-------------------------+ | users | +-------------------------+ | {field0=Bob, field1=38} | +-------------------------+ ``` # Alterar nomes de campo em matrizes com uso de `CAST` Para alterar o nome de campo em uma matriz que contenha valores `ROW`, você pode `CAST` a declaração `ROW`: ``` WITH dataset AS ( SELECT CAST( ROW('Bob', 38) AS ROW(name VARCHAR, age INTEGER) ) AS users ) SELECT * FROM dataset ``` Essa consulta retorna: ``` +--------------------+ | users | +--------------------+ | {NAME=Bob, AGE=38} | +--------------------+ ``` **nota** No exemplo acima, você declara `name` como um `VARCHAR` , porque esse é o tipo no Presto. Se você declarar esse `STRUCT` dentro de uma instrução `CREATE TABLE`, use o tipo `String` porque o Hive define esse tipo de dados como `String`. # Filtrar matrizes com uso da notação `.` No exemplo a seguir, selecione o campo `accountId` na coluna `userIdentity` de uma tabela de logs do AWS CloudTrail usando a notação `.`. Para obter mais informações, consulte [Consultar logs do AWS CloudTrail](cloudtrail-logs.md). ``` SELECT CAST(useridentity.accountid AS bigint) as newid FROM cloudtrail_logs LIMIT 2; ``` Essa consulta retorna: ``` +--------------+ | newid | +--------------+ | 112233445566 | +--------------+ | 998877665544 | +--------------+ ``` Para consultar um conjunto de valores, execute esta consulta: ``` WITH dataset AS ( SELECT ARRAY[ CAST(ROW('Bob', 38) AS ROW(name VARCHAR, age INTEGER)), CAST(ROW('Alice', 35) AS ROW(name VARCHAR, age INTEGER)), CAST(ROW('Jane', 27) AS ROW(name VARCHAR, age INTEGER)) ] AS users ) SELECT * FROM dataset ``` Ela retorna este resultado: ``` +-----------------------------------------------------------------+ | users | +-----------------------------------------------------------------+ | [{NAME=Bob, AGE=38}, {NAME=Alice, AGE=35}, {NAME=Jane, AGE=27}] | +-----------------------------------------------------------------+ ``` # Filtrar matrizes com valores aninhados Matrizes grandes normalmente contêm estruturas aninhadas, e você precisa ser capaz de filtrar ou pesquisar valores dentro delas. Para definir um conjunto de dados para uma matriz de valores que inclui um valor `BOOLEAN` aninhado, execute esta consulta: ``` WITH dataset AS ( SELECT CAST( ROW('aws.amazon.com', ROW(true)) AS ROW(hostname VARCHAR, flaggedActivity ROW(isNew BOOLEAN)) ) AS sites ) SELECT * FROM dataset ``` Ela retorna este resultado: ``` +----------------------------------------------------------+ | sites | +----------------------------------------------------------+ | {HOSTNAME=aws.amazon.com, FLAGGEDACTIVITY={ISNEW=true}} | +----------------------------------------------------------+ ``` Em seguida, para filtrar e acessar o valor `BOOLEAN` desse elemento, continue usando a notação `.` ``` WITH dataset AS ( SELECT CAST( ROW('aws.amazon.com', ROW(true)) AS ROW(hostname VARCHAR, flaggedActivity ROW(isNew BOOLEAN)) ) AS sites ) SELECT sites.hostname, sites.flaggedactivity.isnew FROM dataset ``` Essa consulta seleciona os campos aninhados e retorna este resultado: ``` +------------------------+ | hostname | isnew | +------------------------+ | aws.amazon.com | true | +------------------------+ ``` # Filtrar matrizes com uso de `UNNEST` Para filtrar uma matriz que inclua uma estrutura aninhada por um dos elementos filho, emita uma consulta com um operador `UNNEST`. Para obter mais informações sobre `UNNEST`, consulte [Nivelar matrizes aninhadas](flattening-arrays.md). Por exemplo, esta consulta encontra nomes de host de sites no conjunto de dados. ``` WITH dataset AS ( SELECT ARRAY[ CAST( ROW('aws.amazon.com', ROW(true)) AS ROW(hostname VARCHAR, flaggedActivity ROW(isNew BOOLEAN)) ), CAST( ROW('news.cnn.com', ROW(false)) AS ROW(hostname VARCHAR, flaggedActivity ROW(isNew BOOLEAN)) ), CAST( ROW('netflix.com', ROW(false)) AS ROW(hostname VARCHAR, flaggedActivity ROW(isNew BOOLEAN)) ) ] as items ) SELECT sites.hostname, sites.flaggedActivity.isNew FROM dataset, UNNEST(items) t(sites) WHERE sites.flaggedActivity.isNew = true ``` Ela retorna: ``` +------------------------+ | hostname | isnew | +------------------------+ | aws.amazon.com | true | +------------------------+ ``` # Localizar palavras-chave em matrizes usando `regexp_like` Os exemplos a seguir ilustram como pesquisar uma palavra-chave em um conjunto de dados em um elemento dentro de uma matriz usando a função [regexp\$1like](https://prestodb.io/docs/current/functions/regexp.html). Ele usa como entrada um padrão de expressão regular para avaliar ou uma lista de termos separados por uma barra vertical (\$1), avalia o padrão e determina se a string especificada a contém. O padrão da expressão regular precisa estar contido na string e não precisa corresponder a ela. Para corresponder à string inteira, coloque o padrão com ^ no início e \$1 no final, como `'^pattern$'`. Considere uma matriz de sites contendo os respectivos nomes de host e um elemento `flaggedActivity`. Esse elemento inclui um `ARRAY`, contendo vários elementos `MAP`, cada um listando palavras-chave conhecidas diferentes e a contagem de popularidade. Suponhamos que você encontre uma palavra-chave dentro de um `MAP` nesta matriz. Para pesquisar esse conjunto de dados para sites com uma palavra-chave específica, usamos `regexp_like` em vez do operador SQL `LIKE` semelhante, porque a pesquisa de um grande número de palavras-chave é mais eficiente com `regexp_like`. **Example Exemplo 1: uso do `regexp_like`** A consulta neste exemplo usa a função `regexp_like` para pesquisar os termos `'politics|bigdata'` encontrados em valores em matrizes: ``` WITH dataset AS ( SELECT ARRAY[ CAST( ROW('aws.amazon.com', ROW(ARRAY[ MAP(ARRAY['term', 'count'], ARRAY['bigdata', '10']), MAP(ARRAY['term', 'count'], ARRAY['serverless', '50']), MAP(ARRAY['term', 'count'], ARRAY['analytics', '82']), MAP(ARRAY['term', 'count'], ARRAY['iot', '74']) ]) ) AS ROW(hostname VARCHAR, flaggedActivity ROW(flags ARRAY(MAP(VARCHAR, VARCHAR)) )) ), CAST( ROW('news.cnn.com', ROW(ARRAY[ MAP(ARRAY['term', 'count'], ARRAY['politics', '241']), MAP(ARRAY['term', 'count'], ARRAY['technology', '211']), MAP(ARRAY['term', 'count'], ARRAY['serverless', '25']), MAP(ARRAY['term', 'count'], ARRAY['iot', '170']) ]) ) AS ROW(hostname VARCHAR, flaggedActivity ROW(flags ARRAY(MAP(VARCHAR, VARCHAR)) )) ), CAST( ROW('netflix.com', ROW(ARRAY[ MAP(ARRAY['term', 'count'], ARRAY['cartoons', '1020']), MAP(ARRAY['term', 'count'], ARRAY['house of cards', '112042']), MAP(ARRAY['term', 'count'], ARRAY['orange is the new black', '342']), MAP(ARRAY['term', 'count'], ARRAY['iot', '4']) ]) ) AS ROW(hostname VARCHAR, flaggedActivity ROW(flags ARRAY(MAP(VARCHAR, VARCHAR)) )) ) ] AS items ), sites AS ( SELECT sites.hostname, sites.flaggedactivity FROM dataset, UNNEST(items) t(sites) ) SELECT hostname FROM sites, UNNEST(sites.flaggedActivity.flags) t(flags) WHERE regexp_like(flags['term'], 'politics|bigdata') GROUP BY (hostname) ``` Essa consulta retorna dois sites: ``` +----------------+ | hostname | +----------------+ | aws.amazon.com | +----------------+ | news.cnn.com | +----------------+ ``` **Example Exemplo 2: uso do `regexp_like`** A consulta no exemplo a seguir agrega ao total de pontuações de popularidade dos sites correspondentes aos termos de pesquisa com a função `regexp_like` e, em seguida, ordena da mais alta para a mais baixa. ``` WITH dataset AS ( SELECT ARRAY[ CAST( ROW('aws.amazon.com', ROW(ARRAY[ MAP(ARRAY['term', 'count'], ARRAY['bigdata', '10']), MAP(ARRAY['term', 'count'], ARRAY['serverless', '50']), MAP(ARRAY['term', 'count'], ARRAY['analytics', '82']), MAP(ARRAY['term', 'count'], ARRAY['iot', '74']) ]) ) AS ROW(hostname VARCHAR, flaggedActivity ROW(flags ARRAY(MAP(VARCHAR, VARCHAR)) )) ), CAST( ROW('news.cnn.com', ROW(ARRAY[ MAP(ARRAY['term', 'count'], ARRAY['politics', '241']), MAP(ARRAY['term', 'count'], ARRAY['technology', '211']), MAP(ARRAY['term', 'count'], ARRAY['serverless', '25']), MAP(ARRAY['term', 'count'], ARRAY['iot', '170']) ]) ) AS ROW(hostname VARCHAR, flaggedActivity ROW(flags ARRAY(MAP(VARCHAR, VARCHAR)) )) ), CAST( ROW('netflix.com', ROW(ARRAY[ MAP(ARRAY['term', 'count'], ARRAY['cartoons', '1020']), MAP(ARRAY['term', 'count'], ARRAY['house of cards', '112042']), MAP(ARRAY['term', 'count'], ARRAY['orange is the new black', '342']), MAP(ARRAY['term', 'count'], ARRAY['iot', '4']) ]) ) AS ROW(hostname VARCHAR, flaggedActivity ROW(flags ARRAY(MAP(VARCHAR, VARCHAR)) )) ) ] AS items ), sites AS ( SELECT sites.hostname, sites.flaggedactivity FROM dataset, UNNEST(items) t(sites) ) SELECT hostname, array_agg(flags['term']) AS terms, SUM(CAST(flags['count'] AS INTEGER)) AS total FROM sites, UNNEST(sites.flaggedActivity.flags) t(flags) WHERE regexp_like(flags['term'], 'politics|bigdata') GROUP BY (hostname) ORDER BY total DESC ``` Essa consulta retorna dois sites: ``` +------------------------------------+ | hostname | terms | total | +----------------+-------------------+ | news.cnn.com | politics | 241 | +----------------+-------------------+ | aws.amazon.com | bigdata | 10 | +----------------+-------------------+ ``` # Consultar dados geoespaciais Os dados geoespaciais contêm identificadores que especificam uma posição geográfica para um objeto. Entre os exemplos desse tipo de dados estão previsões do tempo, rotas em mapa, tweets com posições geográficas, locais de lojas e rotas aéreas. Os dados geoespaciais têm uma função importante na analytics comercial, na geração de relatórios e na previsão. Os identificadores geoespaciais, como latitude e longitude, permitem converter qualquer endereço postal em um conjunto de coordenadas geográficas. ## O que é uma consulta geoespacial? As consultas geoespaciais são tipos especializados de consultas SQL disponíveis no Athena. Elas diferem de consultas SQL não espaciais das seguintes maneiras: + Usando os seguintes tipos de dados de geometria especializados: `point`, `line`, `multiline`, `polygon`e `multipolygon`. + Expressando relacionamentos entre tipos de dados, como geometria `distance`, `equals`, `crosses`, `touches`, `overlaps`, `disjoint` e outros. Com as consultas geoespaciais no Athena, você pode executar estas e outras operações semelhantes: + Encontrar a distância entre dois pontos. + Verificar se uma área (polígono) contém outra. + Verifique se uma linha cruza ou toca outra linha ou polígono. Por exemplo, para obter um tipo de dados de geometria `point` de valores do tipo `double` para as coordenadas geográficas do Monte Rainier no Athena, use a função geoespacial `ST_Point (longitude, latitude)`, como no exemplo a seguir. ``` ST_Point(-121.7602, 46.8527) ``` ## Formatos de dados de entrada e tipos de dados de geometria Para usar as funções geoespaciais no Athena, insira os dados no formato WKT ou use o SerDe JSON do Hive. Você também pode usar os tipos de dados de geometria disponíveis no Athena. ### Formatos de dados de entrada Para processar as consultas geoespaciais, o Athena permite a entrada de dados nestes formatos: + **Well-Known Text (WKT – Texto bem conhecido)**. No Athena, o WKT é representado como um tipo de dados `varchar(x)` ou `string`. + **Dados geoespaciais codificados por JSON**. Para analisar arquivos JSON com dados geoespaciais e criar tabelas para eles, o Athena usa o [SerDe JSON do Hive](https://github.com/Esri/spatial-framework-for-hadoop/wiki/Hive-JSON-SerDe). Para obter mais informações sobre como usar esse SerDe no Athena, consulte [Bibliotecas SerDe JSON](json-serde.md). ### Tipos de dados de geometria Para processar as consultas geoespaciais, o Athena aceita os seguintes tipos de dados de geometria especializados: + `point` + `line` + `polygon` + `multiline` + `multipolygon` ## Funções geoespaciais aceitas Para obter informações sobre as funções geoespaciais no mecanismo Athena versão 3, consulte [Geospatial functions](https://trino.io/docs/current/functions/geospatial.html) (Funções geoespaciais) na documentação do Trino. # Exemplos: consultas geoespaciais Os exemplos neste tópico criam duas tabelas de dados de exemplo disponíveis no GitHub e consultam as tabelas com base nos dados. Os dados de exemplo, que são apenas para fins ilustrativos e não têm garantia de serem precisos, estão nos seguintes arquivos: + **[https://github.com/Esri/gis-tools-for-hadoop/blob/master/samples/data/earthquake-data/earthquakes.csv](https://github.com/Esri/gis-tools-for-hadoop/blob/master/samples/data/earthquake-data/earthquakes.csv)** – lista terremotos ocorridos na Califórnia. A tabela `earthquakes` de exemplo usa campos desses dados. + **[https://github.com/Esri/gis-tools-for-hadoop/blob/master/samples/data/counties-data/california-counties.json](https://github.com/Esri/gis-tools-for-hadoop/blob/master/samples/data/counties-data/california-counties.json)**: lista os dados do condado no estado da Califórnia no [formato GeoJSON compatível com ESRI](https://doc.arcgis.com/en/arcgis-online/reference/geojson.htm). Os dados incluem muitos campos, como `AREA`, `PERIMETER`, `STATE`, `COUNTY` e `NAME`, mas a tabela `counties` de exemplo usa apenas dois: `Name` (string) e `BoundaryShape` (binário). **nota** O Athena usa `com.esri.json.hadoop.EnclosedEsriJsonInputFormat` para converter os dados JSON no formato binário geoespacial. O exemplo de código a seguir cria uma tabela chamada `earthquakes`: ``` CREATE external TABLE earthquakes ( earthquake_date string, latitude double, longitude double, depth double, magnitude double, magtype string, mbstations string, gap string, distance string, rms string, source string, eventid string ) ROW FORMAT DELIMITED FIELDS TERMINATED BY ',' STORED AS TEXTFILE LOCATION 's3://amzn-s3-demo-bucket/my-query-log/csv/'; ``` O exemplo de código a seguir cria uma tabela chamada `counties`: ``` CREATE external TABLE IF NOT EXISTS counties ( Name string, BoundaryShape binary ) ROW FORMAT SERDE 'com.esri.hadoop.hive.serde.EsriJsonSerDe' STORED AS INPUTFORMAT 'com.esri.json.hadoop.EnclosedEsriJsonInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/my-query-log/json/'; ``` A consulta de exemplo a seguir usa a função `CROSS JOIN` nas tabelas `counties` e `earthquake`. O exemplo usa `ST_CONTAINS` para consultar os condados com limites que incluem locais de terremoto, que são especificados com `ST_POINT`. A consulta agrupa esses condados por nome, ordena-os por contagem e os retorna em ordem decrescente. ``` SELECT counties.name, COUNT(*) cnt FROM counties CROSS JOIN earthquakes WHERE ST_CONTAINS (ST_GeomFromLegacyBinary(counties.boundaryshape), ST_POINT(earthquakes.longitude, earthquakes.latitude)) GROUP BY counties.name ORDER BY cnt DESC ``` Essa consulta retorna: ``` +------------------------+ | name | cnt | +------------------------+ | Kern | 36 | +------------------------+ | San Bernardino | 35 | +------------------------+ | Imperial | 28 | +------------------------+ | Inyo | 20 | +------------------------+ | Los Angeles | 18 | +------------------------+ | Riverside | 14 | +------------------------+ | Monterey | 14 | +------------------------+ | Santa Clara | 12 | +------------------------+ | San Benito | 11 | +------------------------+ | Fresno | 11 | +------------------------+ | San Diego | 7 | +------------------------+ | Santa Cruz | 5 | +------------------------+ | Ventura | 3 | +------------------------+ | San Luis Obispo | 3 | +------------------------+ | Orange | 2 | +------------------------+ | San Mateo | 1 | +------------------------+ ``` ## Recursos adicionais Para ver exemplos adicionais de consultas geoespaciais, consulte as seguintes postagens de blog: + [Estenda consultas geoespaciais no Amazon Athena com UDFs e AWS Lambda](https://aws.amazon.com/blogs/big-data/extend-geospatial-queries-in-amazon-athena-with-udfs-and-aws-lambda/) + [Visualize mais de 200 anos de dados climáticos globais usando o Amazon Athena e o Amazon Quick](https://aws.amazon.com/blogs/big-data/visualize-over-200-years-of-global-climate-data-using-amazon-athena-and-amazon-quicksight/). + [Querying OpenStreetMap with Amazon Athena (Consultar OpenStreetMap com o Amazon Athena](https://aws.amazon.com/blogs/big-data/querying-openstreetmap-with-amazon-athena/) # Consultar dados JSON O Amazon Athena permite analisar dados codificados em JSON, extrair dados JSON aninhado, pesquisar valores e saber o comprimento e o tamanho dos arrays JSON. Para aprender os fundamentos da consulta de dados JSON no Athena, considere os seguintes exemplos de dados do planeta: ``` {name:"Mercury",distanceFromSun:0.39,orbitalPeriod:0.24,dayLength:58.65} {name:"Venus",distanceFromSun:0.72,orbitalPeriod:0.62,dayLength:243.02} {name:"Earth",distanceFromSun:1.00,orbitalPeriod:1.00,dayLength:1.00} {name:"Mars",distanceFromSun:1.52,orbitalPeriod:1.88,dayLength:1.03} ``` Observe como cada registro (basicamente, cada linha na tabela) está em uma linha diferente. Para consultar os dados JSON, você pode usar uma declaração `CREATE TABLE` como a seguinte: ``` CREATE EXTERNAL TABLE `planets_json`( `name` string, `distancefromsun` double, `orbitalperiod` double, `daylength` double) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.IgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/json/' ``` Para consultar os dados, use uma declaração `SELECT` como a seguinte. ``` SELECT * FROM planets_json ``` Os resultados da consulta são semelhantes aos seguintes: **** | \$1 | name | distância do sol | período orbital | duração do dia | | --- | --- | --- | --- | --- | | 1 | Mercúrio | 0,39 | 0,24 | 58,65 | | 2 | Vênus | 0,72 | 0,62 | 243,02 | | 3 | Terra | 1.0 | 1.0 | 1,0 | | 4 | Marte | 1,52 | 1,88 | 1,03 | Observe como a declaração `CREATE TABLE` usa [OpenX JSON SerDe](openx-json-serde.md), o que exige que cada registro JSON esteja em uma linha diferente. Se o JSON estiver em um formato pretty print ou se todos os registros estiverem em uma única linha, os dados não serão lidos corretamente. Para consultar dados JSON que estejam em um formato pretty print, você pode usar [Amazon Ion Hive SerDe](ion-serde.md) em vez do OpenX JSON SerDe. Considere os dados anteriores armazenados em um formato pretty print: ``` { name:"Mercury", distanceFromSun:0.39, orbitalPeriod:0.24, dayLength:58.65 } { name:"Venus", distanceFromSun:0.72, orbitalPeriod:0.62, dayLength:243.02 } { name:"Earth", distanceFromSun:1.00, orbitalPeriod:1.00, dayLength:1.00 } { name:"Mars", distanceFromSun:1.52, orbitalPeriod:1.88, dayLength:1.03 } ``` Para consultar esses dados sem reformatar, você pode usar uma declaração `CREATE TABLE` como a seguinte. Observe que, em vez de especificar o OpenX JSON SerDe, a instrução especifica `STORED AS ION`. ``` CREATE EXTERNAL TABLE `planets_ion`( `name` string, `distancefromsun` DECIMAL(10, 2), `orbitalperiod` DECIMAL(10, 2), `daylength` DECIMAL(10, 2)) STORED AS ION LOCATION 's3://amzn-s3-demo-bucket/json-ion/' ``` A consulta `SELECT * FROM planets_ion` produz os mesmos resultados de antes. Para obter mais informações sobre a criação de tabelas dessa forma usando o Amazon Ion Hive SerDe, consulte [Criar tabelas do Amazon Ion](ion-serde-using-create-table.md). O exemplo anterior de dados JSON não contém tipos de dados complexos, como arrays ou estruturas aninhadas. Para obter mais informações sobre como consultar dados JSON aninhado, consulte [Exemplo: desserializar JSON aninhado](openx-json-serde.md#nested-json-serde-example). **Topics** + [Práticas recomendadas de leitura de dados JSON](parsing-json-data.md) + [Extrair dados JSON de strings](extracting-data-from-JSON.md) + [Pesquisar por valores em matrizes JSON](searching-for-values.md) + [Obter comprimento e tamanho de matrizes JSON](length-and-size.md) + [Solução de problemas de consultas JSON](json-troubleshooting.md) # Práticas recomendadas de leitura de dados JSON JavaScript Object Notation (JSON) é um método comum para codificar estruturas de dados como texto. Muitos aplicativos e ferramentas produzem dados codificados em JSON. No Amazon Athena, você pode criar tabelas com base em dados externos e incluir dados codificados em JSON nelas. Para esses tipos de dados de origem, use o Athena junto com [Bibliotecas SerDe JSON](json-serde.md). Use as seguintes dicas para ler dados codificados por JSON: + Escolha o SerDe certo: um JSON SerDe nativo, `org.apache.hive.hcatalog.data.JsonSerDe`; ou um OpenX SerDe, `org.openx.data.jsonserde.JsonSerDe`. Para obter mais informações, consulte [Bibliotecas SerDe JSON](json-serde.md). + Certifique-se de que cada registro codificado em JSON seja representado em uma linha separada, não formatado para impressão. **nota** O SerDe espera que cada documento JSON esteja em uma única linha de texto, sem caracteres de terminação de linha separando os campos no registro. Se o texto JSON estiver formatado para impressão, você poderá receber uma mensagem de erro como HIVE\$1CURSOR\$1ERROR: Row is not a valid JSON Object (HIVE\$1CURSOR\$1ERROR: a linha não é um objeto JSON válido) ou HIVE\$1CURSOR\$1ERROR: JsonParseException: Unexpected end-of-input: expected close marker for OBJECT (HIVE\$1CURSOR\$1ERROR: JSONParseException: Fim de entrada inesperado: marcador de fechamento esperado para OBJECT) quando tentar consultar a tabela após criá-la. Para obter mais informações, consulte [JSON Data Files](https://github.com/rcongiu/Hive-JSON-Serde#json-data-files) na documentação do OpenX SerDe no GitHub. + Gere seus dados codificados por JSON em colunas sem distinção entre letras maiúsculas e minúsculas. + Forneça uma opção para ignorar registros malformadas, como neste exemplo. ``` CREATE EXTERNAL TABLE json_table ( column_a string, column_b int ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ('ignore.malformed.json' = 'true') LOCATION 's3://amzn-s3-demo-bucket/path/'; ``` + Converta os campos nos dados de origem que tenham um esquema indeterminado em strings codificadas em JSON no Athena. Ao criar tabelas com os dados do JSON, o Athena analisa os dados com base no esquema existente e predefinido. No entanto, nem todos os dados podem ter um esquema predefinido. Para simplificar o gerenciamento de esquemas nesses casos, costuma ser útil converter os campos nos dados de origem que têm um esquema indeterminado em strings JSON no Athena e usar [Bibliotecas SerDe JSON](json-serde.md). Por exemplo, considere um aplicativo IoT que publique eventos com campos comuns de sensores diferentes. Um desses campos deve armazenar uma carga útil personalizada que seja exclusiva do sensor que envia o evento. Nesse caso, como você não sabe o esquema, recomendamos armazenar as informações como uma string codificada em JSON. Para isso, converta os dados na tabela do Athena em JSON, como no exemplo a seguir. Você também pode converter os dados codificados em JSON em tipos de dados do Athena. **Topics** + [Converter tipos de dados do Athena em JSON](converting-native-data-types-to-json.md) + [Converter JSON em tipos de dados do Athena](converting-json-to-native-data-types.md) # Converter tipos de dados do Athena em JSON Para converter os tipos de dados do Athena em JSON, use `CAST`. ``` WITH dataset AS ( SELECT CAST('HELLO ATHENA' AS JSON) AS hello_msg, CAST(12345 AS JSON) AS some_int, CAST(MAP(ARRAY['a', 'b'], ARRAY[1,2]) AS JSON) AS some_map ) SELECT * FROM dataset ``` Essa consulta retorna: ``` +-------------------------------------------+ | hello_msg | some_int | some_map | +-------------------------------------------+ | "HELLO ATHENA" | 12345 | {"a":1,"b":2} | +-------------------------------------------+ ``` # Converter JSON em tipos de dados do Athena Para converter os dados do JSON em tipos de dados do Athena, use `CAST`. **nota** Neste exemplo, para denotar strings como codificadas em JSON, comece com a palavra-chave `JSON` e use aspas simples, como `JSON '12345'` ``` WITH dataset AS ( SELECT CAST(JSON '"HELLO ATHENA"' AS VARCHAR) AS hello_msg, CAST(JSON '12345' AS INTEGER) AS some_int, CAST(JSON '{"a":1,"b":2}' AS MAP(VARCHAR, INTEGER)) AS some_map ) SELECT * FROM dataset ``` Essa consulta retorna: ``` +-------------------------------------+ | hello_msg | some_int | some_map | +-------------------------------------+ | HELLO ATHENA | 12345 | {a:1,b:2} | +-------------------------------------+ ``` # Extrair dados JSON de strings Você pode ter dados de origem contendo strings codificadas em JSON que não deseja necessariamente desserializar em uma tabela no Athena. Neste caso, você ainda pode executar operações SQL nesses dados usando as funções JSON disponíveis no Presto. Considere essa string JSON como um conjunto de dados de exemplo. ``` {"name": "Susan Smith", "org": "engineering", "projects": [ {"name":"project1", "completed":false}, {"name":"project2", "completed":true} ] } ``` ## Exemplos: extração de propriedades Para extrair as propriedades `name` e `projects` da string JSON, use a função `json_extract` como no exemplo a seguir. A função `json_extract` utiliza a coluna que contém a string JSON e a pesquisa usando uma expressão como `JSONPath` com a notação `.` **nota** `JSONPath` realiza um transversal de árvore simples. Ele usa o sinal `$` para denotar a raiz do documento JSON, seguido de um ponto final e um elemento aninhado diretamente na raiz, como `$.name`. ``` WITH dataset AS ( SELECT '{"name": "Susan Smith", "org": "engineering", "projects": [{"name":"project1", "completed":false}, {"name":"project2", "completed":true}]}' AS myblob ) SELECT json_extract(myblob, '$.name') AS name, json_extract(myblob, '$.projects') AS projects FROM dataset ``` O valor retornado é uma string codificada em JSON, e não um tipo de dados nativo do Athena. ``` +-----------------------------------------------------------------------------------------------+ | name | projects | +-----------------------------------------------------------------------------------------------+ | "Susan Smith" | [{"name":"project1","completed":false},{"name":"project2","completed":true}] | +-----------------------------------------------------------------------------------------------+ ``` Para extrair o valor escalar da string JSON, use a função `json_extract_scalar(json, json_path)`. É semelhante ao `json_extract`, mas retorna um valor de string `varchar` em vez de uma string codificada em JSON. O valor do parâmetro *json\$1path* deve ser um escalar (um booleano, número ou string). **nota** Não use a função `json_extract_scalar` em matrizes, mapas ou structs. ``` WITH dataset AS ( SELECT '{"name": "Susan Smith", "org": "engineering", "projects": [{"name":"project1", "completed":false},{"name":"project2", "completed":true}]}' AS myblob ) SELECT json_extract_scalar(myblob, '$.name') AS name, json_extract_scalar(myblob, '$.projects') AS projects FROM dataset ``` Essa consulta retorna: ``` +---------------------------+ | name | projects | +---------------------------+ | Susan Smith | | +---------------------------+ ``` Para obter o primeiro elemento da propriedade `projects` na matriz de exemplo, use a função `json_array_get` e especifique a posição de índice. ``` WITH dataset AS ( SELECT '{"name": "Bob Smith", "org": "engineering", "projects": [{"name":"project1", "completed":false},{"name":"project2", "completed":true}]}' AS myblob ) SELECT json_array_get(json_extract(myblob, '$.projects'), 0) AS item FROM dataset ``` Ele retorna o valor na posição de índice especificada na matriz codificada em JSON. ``` +---------------------------------------+ | item | +---------------------------------------+ | {"name":"project1","completed":false} | +---------------------------------------+ ``` Para retornar um tipo de string do Athena, use o operador `[]` dentro de uma expressão `JSONPath` e use a função `json_extract_scalar`. Para obter mais informações sobre o `[]`, consulte [Acessar elementos de matrizes](accessing-array-elements.md). ``` WITH dataset AS ( SELECT '{"name": "Bob Smith", "org": "engineering", "projects": [{"name":"project1", "completed":false},{"name":"project2", "completed":true}]}' AS myblob ) SELECT json_extract_scalar(myblob, '$.projects[0].name') AS project_name FROM dataset ``` Ela retorna este resultado: ``` +--------------+ | project_name | +--------------+ | project1 | +--------------+ ``` # Pesquisar por valores em matrizes JSON Para determinar se um valor específico existe dentro de uma matriz codificada em JSON, use a função `json_array_contains`. A consulta a seguir lista os nomes dos usuários que estão participando de "project2". ``` WITH dataset AS ( SELECT * FROM (VALUES (JSON '{"name": "Bob Smith", "org": "legal", "projects": ["project1"]}'), (JSON '{"name": "Susan Smith", "org": "engineering", "projects": ["project1", "project2", "project3"]}'), (JSON '{"name": "Jane Smith", "org": "finance", "projects": ["project1", "project2"]}') ) AS t (users) ) SELECT json_extract_scalar(users, '$.name') AS user FROM dataset WHERE json_array_contains(json_extract(users, '$.projects'), 'project2') ``` Essa consulta retorna uma lista de usuários. ``` +-------------+ | user | +-------------+ | Susan Smith | +-------------+ | Jane Smith | +-------------+ ``` O exemplo de consulta a seguir lista os nomes de usuários que concluíram projetos com o número total de projetos realizados. Ele realiza estas ações: + Usa instruções `SELECT` aninhadas para fins de clareza. + Extrai a matriz de projetos. + Converte a matriz em uma matriz nativa de pares de chave/valor usando `CAST`. + Extrai cada elemento de matriz individual usando o operador `UNNEST`. + Filtra valores obtidos por projetos concluídos e os conta. **nota** Ao usar `CAST` em `MAP`, você pode especificar o elemento de chave como `VARCHAR` (String nativa no Presto), mas deixar o valor como JSON, porque os valores no `MAP` são de tipos diferentes: string para o primeiro par de chave/valor e Booliano para o segundo. ``` WITH dataset AS ( SELECT * FROM (VALUES (JSON '{"name": "Bob Smith", "org": "legal", "projects": [{"name":"project1", "completed":false}]}'), (JSON '{"name": "Susan Smith", "org": "engineering", "projects": [{"name":"project2", "completed":true}, {"name":"project3", "completed":true}]}'), (JSON '{"name": "Jane Smith", "org": "finance", "projects": [{"name":"project2", "completed":true}]}') ) AS t (users) ), employees AS ( SELECT users, CAST(json_extract(users, '$.projects') AS ARRAY(MAP(VARCHAR, JSON))) AS projects_array FROM dataset ), names AS ( SELECT json_extract_scalar(users, '$.name') AS name, projects FROM employees, UNNEST (projects_array) AS t(projects) ) SELECT name, count(projects) AS completed_projects FROM names WHERE cast(element_at(projects, 'completed') AS BOOLEAN) = true GROUP BY name ``` Esta consulta retorna o seguinte resultado: ``` +----------------------------------+ | name | completed_projects | +----------------------------------+ | Susan Smith | 2 | +----------------------------------+ | Jane Smith | 1 | +----------------------------------+ ``` # Obter comprimento e tamanho de matrizes JSON Para obter o comprimento e o tamanho de matrizes JSON, é possível usar as funções `json_array_length` e `json_size`. ## Exemplo: `json_array_length` Para obter o tamanho de uma matriz codificada em JSON, use a função `json_array_length`. ``` WITH dataset AS ( SELECT * FROM (VALUES (JSON '{"name": "Bob Smith", "org": "legal", "projects": [{"name":"project1", "completed":false}]}'), (JSON '{"name": "Susan Smith", "org": "engineering", "projects": [{"name":"project2", "completed":true}, {"name":"project3", "completed":true}]}'), (JSON '{"name": "Jane Smith", "org": "finance", "projects": [{"name":"project2", "completed":true}]}') ) AS t (users) ) SELECT json_extract_scalar(users, '$.name') as name, json_array_length(json_extract(users, '$.projects')) as count FROM dataset ORDER BY count DESC ``` Essa consulta retorna este resultado: ``` +---------------------+ | name | count | +---------------------+ | Susan Smith | 2 | +---------------------+ | Bob Smith | 1 | +---------------------+ | Jane Smith | 1 | +---------------------+ ``` ## Exemplo: `json_size` Para obter o tamanho de uma matriz ou de um objeto codificado em JSON, use a função `json_size` e especifique a coluna que contém a string JSON e a expressão `JSONPath` para a matriz ou o objeto. ``` WITH dataset AS ( SELECT * FROM (VALUES (JSON '{"name": "Bob Smith", "org": "legal", "projects": [{"name":"project1", "completed":false}]}'), (JSON '{"name": "Susan Smith", "org": "engineering", "projects": [{"name":"project2", "completed":true},{"name":"project3", "completed":true}]}'), (JSON '{"name": "Jane Smith", "org": "finance", "projects": [{"name":"project2", "completed":true}]}') ) AS t (users) ) SELECT json_extract_scalar(users, '$.name') as name, json_size(users, '$.projects') as count FROM dataset ORDER BY count DESC ``` Essa consulta retorna este resultado: ``` +---------------------+ | name | count | +---------------------+ | Susan Smith | 2 | +---------------------+ | Bob Smith | 1 | +---------------------+ | Jane Smith | 1 | +---------------------+ ``` # Solução de problemas de consultas JSON Para obter ajuda sobre como solucionar problemas com consultas relacionadas ao JSON, leia [Erros relacionados ao JSON](troubleshooting-athena.md#troubleshooting-athena-json-related-errors) ou acesse os seguintes recursos: + [Recebo mensagens de erro ao tentar ler dados JSON no Amazon Athena](https://aws.amazon.com/premiumsupport/knowledge-center/error-json-athena/) + [Como resolver o erro “HIVE\$1CURSOR\$1ERROR: A linha não é um objeto JSON válido - JSONException: Chave duplicada” ao ler arquivos do AWS Config no Athena?)](https://aws.amazon.com/premiumsupport/knowledge-center/json-duplicate-key-error-athena-config/) + [A consulta SELECT COUNT no Amazon Athena retorna somente um registro, embora o arquivo JSON de entrada tenha vários registros](https://aws.amazon.com/premiumsupport/knowledge-center/select-count-query-athena-json-records/) + [Como posso ver o arquivo de origem do Amazon S3 para uma linha em uma tabela do Athena?](https://aws.amazon.com/premiumsupport/knowledge-center/find-s3-source-file-athena-table-row/) Consulte também [Considerações e limitações das consultas SQL no Amazon Athena](other-notable-limitations.md). # Usar Machine Learning (ML) com o Amazon Athena O Machine Learning (ML) com Amazon Athena permite que você use o Athena para escrever instruções SQL que executam inferências de Machine Learning (ML) por meio da IA do Amazon SageMaker AI. Esse recurso simplifica o acesso a modelos de ML para análise de dados, eliminando a necessidade de usar métodos de programação complexos para executar inferências. Para usar ML com Athena, você define uma função ML com Athena usando a cláusula `USING EXTERNAL FUNCTION`. A função aponta para o endpoint do modelo do SageMaker AI que você deseja usar e especifica os nomes das variáveis e os tipos de dados para transmitir ao modelo. As cláusulas subsequentes na consulta fazem referência à função para passar os valores para o modelo. O modelo executa inferências com base nos valores que a consulta passa e retorna os resultados da inferência. Para obter mais informações sobre o SageMaker AI e como os endpoints de IA dele funcionam, consulte o [Guia do desenvolvedor do Amazon SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/). Para ver um exemplo que usa ML com inferência do Athena e do SageMaker AI para detectar um valor anômalo em um conjunto de resultados, consulte o artigo [Detecting anomalous values by invoking the Amazon Athena machine learning inference function](https://aws.amazon.com/blogs/big-data/detecting-anomalous-values-by-invoking-the-amazon-athena-machine-learning-inference-function/) no Blog de Big Data da AWS. ## Considerações e limitações + **Regiões disponíveis**: o recurso de ML do Athena está disponível nas Regiões da AWS compatíveis com o mecanismo do Athena versão 2 ou posterior. + **O endpoint do modelo do SageMaker AI deve aceitar e retornar `text/csv`**: para obter mais informações sobre formatos de dados, consulte [Common data formats for inference](https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-inference.html) no *Guia do desenvolvedor do Amazon SageMaker AI*. + **O Athena não envia cabeçalhos CSV**: se seu endpoint do SageMaker AI for `text/csv`, o manipulador de entrada não deverá presumir que a primeira linha da entrada seja um cabeçalho CSV. Como o Athena não envia cabeçalhos CSV, a saída retornada ao Athena conterá uma linha a menos do que o esperado pelo Athena e causará um erro. + **Escalabilidade do endpoint do SageMaker AI**: garanta que a escala do endpoint do modelo do SageMaker AI mencionado seja aumentada na vertical o suficiente para chamadas do Athena ao endpoint. Para obter mais informações, consulte [Automatically scale SageMaker models](https://docs.aws.amazon.com/sagemaker/latest/dg/endpoint-auto-scaling.html) no *Guia do desenvolvedor do Amazon SageMaker AI* e [CreateEndpointConfig](https://docs.aws.amazon.com/sagemaker/latest/dg/API_CreateEndpointConfig.html) na *Referência de API do Amazon SageMaker AI*. + **Permissões do IAM**: para executar uma consulta que especifica uma função ML com Athena, a entidade principal do IAM que executa a consulta deve ter permissão para executar a ação `sagemaker:InvokeEndpoint` no endpoint do modelo do SageMaker AI mencionado. Para ter mais informações, consulte [Permitir acesso a ML com o Athena](machine-learning-iam-access.md). + **Não é possível usar as funções ML com Athena diretamente nas cláusulas `GROUP BY`** **Topics** + [Considerações e limitações](#considerations-and-limitations) + [Usar ML com sintaxe do Athena](ml-syntax.md) + [Consultar exemplos de uso de clientes](ml-videos.md) # Usar ML com sintaxe do Athena A cláusula `USING EXTERNAL FUNCTION` especifica uma função ML com Athena ou várias funções que podem ser referenciadas por uma instrução `SELECT` subsequente na consulta. Você define o nome da função, os nomes das variáveis e os tipos de dados das variáveis e dos valores de retorno. ## Resumo A sintaxe a seguir mostra uma cláusula `USING EXTERNAL FUNCTION` que especifica uma função ML com Athena. ``` USING EXTERNAL FUNCTION ml_function_name (variable1 data_type[, variable2 data_type][,...]) RETURNS data_type SAGEMAKER 'sagemaker_endpoint' SELECT ml_function_name() ``` ## Parâmetros **USING EXTERNAL FUNCTION *ml\$1function\$1name* (*variable1* *data\$1type*[, *variable2* *data\$1type*][,...])** *ml\$1function\$1name* define o nome da função, que pode ser usada nas cláusulas de consultas subsequentes. Cada *variable data\$1type* especifica uma variável nomeada e o tipo de dados correspondente que o modelo do SageMaker AI aceita como entrada. O tipo de dados especificado deve ser um permitido pelo Athena. **RETURNS *tipo\$1dados*** *data\$1type* especifica o tipo de dados SQL que *ml\$1function\$1name* retorna para a consulta como saída do modelo do SageMaker AI. **SAGEMAKER '*sagemaker\$1endpoint*'** *sagemaker\$1endpoint* especifica o endpoint do modelo do SageMaker AI. **SELECT [...] *ml\$1function\$1name*(*expression*) [...]** A consulta SELECT que transmite os valores para as variáveis de função e o modelo do SageMaker AI para retornar um resultado. *ml\$1function\$1name* especifica a função que já foi definida na consulta, seguida de uma *expression* que é avaliada para passar os valores. Os valores que são passados e retornados devem coincidir com os tipos de dados correspondentes especificados para a função na cláusula `USING EXTERNAL FUNCTION`. ## Exemplo O exemplo a seguir demonstra uma consulta que usa ML com Athena. **Example** ``` USING EXTERNAL FUNCTION predict_customer_registration(age INTEGER) RETURNS DOUBLE SAGEMAKER 'xgboost-2019-09-20-04-49-29-303' SELECT predict_customer_registration(age) AS probability_of_enrolling, customer_id FROM "sampledb"."ml_test_dataset" WHERE predict_customer_registration(age) < 0.5; ``` # Consultar exemplos de uso de clientes Os vídeos a seguir, que usam a versão de previsualização do Machine Learning (ML) com o Amazon Athena AI, mostram como você pode usar o SageMaker com o Athena. ## Prever a rotatividade de clientes O vídeo a seguir mostra como combinar o Athena com os recursos de machine learning do Amazon SageMaker AI para prever a rotatividade de clientes. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/CUHbSpekRVg/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/CUHbSpekRVg) ## Detectar botnets O vídeo a seguir mostra como uma empresa usa o Amazon Athena e o Amazon SageMaker AI para detectar botnets. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/0dUv-jCt2aw/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/0dUv-jCt2aw) # Consultar com funções definidas pelo usuário As funções definidas pelo usuário (UDFs) no Amazon Athena permitem criar funções personalizadas para processar registros ou grupos de registros. Uma UDF aceita parâmetros, executa o trabalho e retorna um resultado. Para usar uma UDF no Athena, escreva uma cláusula `USING EXTERNAL FUNCTION` antes de uma instrução `SELECT` em uma consulta SQL. A instrução `SELECT` faz referência à UDF e define as variáveis que são passadas para a UDF quando a consulta é executada. A consulta SQL invoca uma função do Lambda usando o runtime Java ao chamar a UDF. As UDFs são definidas dentro da função do Lambda como métodos em um pacote de implantação Java. É possível definir várias UDFs no mesmo pacote de implantação Java para uma função do Lambda. Você também especifica o nome da função do Lambda na cláusula `USING EXTERNAL FUNCTION`. Você tem duas opções para implantar uma função do Lambda para UDFs do Athena. É possível implantar a função diretamente no Lambda ou usar o AWS Serverless Application Repository. Para encontrar as funções do Lambda existentes para UDFs, pesquise no AWS Serverless Application Repository público ou em seu repositório privado e implante-as no Lambda. Você também pode criar ou modificar o código-fonte Java, empacotá-lo em um arquivo JAR e implantá-lo usando o Lambda ou o AWS Serverless Application Repository. Para ver exemplos de código-fonte e pacotes Java para você começar, consulte [Criar e implantar uma UDF com o Lambda](udf-creating-and-deploying.md). Para obter mais informações sobre o Lambda, consulte o [Guia do desenvolvedor do AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/). Consulte mais informações sobre o AWS Serverless Application Repository no [Guia do desenvolvedor do AWS Serverless Application Repository](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/). Para ver um exemplo que usa UDFs com o Athena para traduzir e analisar texto, consulte o artigo no blog do Machine Learning da AWS: [Traduzir e analisar texto usando funções SQL com Amazon Athena, Amazon Translate e Amazon Comprehend](https://aws.amazon.com/blogs/machine-learning/translate-and-analyze-text-using-sql-functions-with-amazon-athena-amazon-translate-and-amazon-comprehend/) (em inglês) ou assista a [video](udf-videos.md#udf-videos-xlate). Para ver um exemplo de uso de UDFs para estender consultas geoespaciais no Amazon Athena, consulte [Estenda consultas geoespaciais no Amazon Athena com UDFs e AWS Lambda](https://aws.amazon.com/blogs/big-data/extend-geospatial-queries-in-amazon-athena-with-udfs-and-aws-lambda/) no *Blog de Big Data da AWS*. **Topics** + [Vídeos sobre UDFs no Athena](udf-videos.md) + [Considerações e limitações](udf-considerations-limitations.md) + [Consultar com uso da sintaxe de consulta de UDFs](udf-query-syntax.md) + [Criar e implantar uma UDF com o Lambda](udf-creating-and-deploying.md) # Vídeos sobre UDFs no Athena Assista aos vídeos a seguir para saber mais como usar as UDFs no Athena. **Vídeo: Apresentação das funções definidas pelo usuário (UDFs) no Amazon Athena** O vídeo a seguir mostra como você pode usar as UDFs no Amazon Athena para editar informações confidenciais. **nota** A sintaxe neste vídeo é pré-lançamento, mas os conceitos são os mesmos. Usar o Athena sem o grupo de trabalho `AmazonAthenaPreviewFunctionality`. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/AxJ6jP4Pfmo/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/AxJ6jP4Pfmo) **Vídeo: Traduzir, analisar e editar campos de texto usando consultas SQL no Amazon Athena** O vídeo a seguir mostra como você pode usar as UDFs no Amazon Athena junto com outros Serviços da AWS para traduzir e analisar texto. **nota** A sintaxe neste vídeo é pré-lançamento, mas os conceitos são os mesmos. Para obter a sintaxe correta, consulte a publicação relacionada no blog: [Traduzir, editar e analisar texto usando funções SQL com Amazon Athena, Amazon Translate e Amazon Comprehend](https://aws.amazon.com/blogs/machine-learning/translate-and-analyze-text-using-sql-functions-with-amazon-athena-amazon-translate-and-amazon-comprehend/) (em inglês) no *blog do Machine Learning da AWS*. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/Od7rXG-WMO4/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/Od7rXG-WMO4) # Considerações e limitações Considere os seguintes pontos ao usar funções definidas pelo usuário (UDFs) no Athena. + **Funções integradas do Athena**: as funções integradas no Athena são desenvolvidas para ter alta performance. Recomendamos usar as funções integradas em lugar das UDFs quando possível. Para obter mais informações sobre funções integradas, consulte [Funções no Amazon Athena](functions.md). + **Somente UDFs escalares**: o Athena aceita somente UDFs escalares, que processam uma linha por vez e retornam um único valor de coluna. O Athena passa um lote de linhas, possivelmente em paralelo, para a UDF sempre que invoca o Lambda. Ao desenvolver UDFs e consultas, esteja ciente do possível impacto desse processamento no tráfego de rede. + **As funções do manipulador UDF usam o formato abreviado**: use o formato abreviado (não o formato completo), para suas funções UDF (por exemplo, `package.Class` em vez de `package.Class::method`). + **Os métodos UDF devem estar em letras minúsculas**: os métodos UDF devem estar em letras minúsculas. Não é permitida a combinação de maiúsculas e minúsculas. + **Os métodos UDF exigem parâmetros**: os métodos UDF devem ter pelo menos um parâmetro de entrada. A tentativa de invocar um UDF definido sem parâmetros de entrada causa uma exceção de runtime. Os UDFs são destinados a executar funções em registros de dados, mas um UDF sem argumentos não recebe dados, então ocorre uma exceção. + **Suporte ao runtime do Java**: atualmente, as UDFs do Athena são compatíveis com os runtimes do Java 8, Java 11 e Java 17 para o Lambda. Para obter mais informações, consulte [Construir funções do Lambda com Java](https://docs.aws.amazon.com/lambda/latest/dg/lambda-java.html) no *Guia do desenvolvedor do AWS Lambda*. **nota** Para o Java 17, você deve definir o valor da variável `JAVA_TOOL_OPTIONS` do ambiente como `--add-opens=java.base/java.nio=ALL-UNNAMED` em seu Lambda. + **Permissões do IAM**: para executar e criar instruções de consulta de UDF no Athena, o principal do IAM que executa a consulta deve ter permissão para executar ações além das funções do Athena. Para obter mais informações, consulte [Permitir acesso a UDFs do Athena: exemplos de políticas](udf-iam-access.md). + **Cotas do Lambda**: as cotas do Lambda se aplicam às UDFs. Para obter mais informações, consulte [Cotas do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/limits.html) no *Guia do desenvolvedor do AWS Lambda*. + **Filtragem em nível de linha** – A filtragem em nível de linha do Lake Formation não é compatível com UDFs. + **Visualizações**: não é possível usar visualizações com UDFs. + **Problemas conhecidos**: para acessar a lista mais recente de problemas conhecidos, consulte [Limitations and issues](https://github.com/awslabs/aws-athena-query-federation/wiki/Limitations_And_Issues) (Limitações e problemas) na seção awslabs/aws-athena-query-federation do GitHub. # Consultar com uso da sintaxe de consulta de UDFs A cláusula `USING EXTERNAL FUNCTION` especifica uma UDF ou várias UDFs que podem ser referenciadas por uma instrução `SELECT` subsequente na consulta. Você precisa do nome do método da UDF e do nome da função do Lambda que hospeda a UDF. No lugar do nome da função do Lambda, você pode usar o ARN do Lambda. Em cenários entre contas, o ARN do Lambda é obrigatório. ## Resumo ``` USING EXTERNAL FUNCTION UDF_name(variable1 data_type[, variable2 data_type][,...]) RETURNS data_type LAMBDA 'lambda_function_name_or_ARN' [, EXTERNAL FUNCTION UDF_name2(variable1 data_type[, variable2 data_type][,...]) RETURNS data_type LAMBDA 'lambda_function_name_or_ARN'[,...]] SELECT [...] UDF_name(expression) [, UDF_name2(expression)] [...] ``` ## Parâmetros **USING EXTERNAL FUNCTION *UDF\$1name*(*variable1* *data\$1type*[, *variable2* *data\$1type*][,...])** *UDF\$1name* especifica o nome da UDF, que deve corresponder a um método Java com a função do Lambda referenciada. Cada *variable data\$1type* especifica uma variável nomeada e o tipo de dados correspondente que a UDF aceita como entrada. O *data\$1type* deve ser um dos tipos de dados do Athena permitidos listados na tabela a seguir e mapear para o tipo de dados Java correspondente. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/udf-query-syntax.html) **RETURNS *tipo\$1dados*** `data_type`O especifica o tipo de dados SQL que a UDF retorna como saída. Os tipos de dados do Athena listados na tabela acima são permitidos. Para o tipo de dados `DECIMAL`, use a sintaxe `RETURNS DECIMAL(precision, scale)` em que *precision* e *scale* são inteiros. **LAMBDA '*lambda\$1function*'** *lambda\$1function* especifica o nome da função do Lambda que será invocada ao executar a UDF. **SELECT [...] *UDF\$1name*(*expression*) [...]** A consulta `SELECT` que passa os valores para a UDF e retorna um resultado. *UDF\$1name* especifica a UDF que será usada, seguida de uma *expressão* que é avaliado para passar os valores. Os valores que são passados e retornados devem coincidir com os tipos de dados correspondentes especificados para a UDF na cláusula `USING EXTERNAL FUNCTION`. ### Exemplos Para ver exemplos de consultas baseadas no código [AthenaUDFHandler.java](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/src/main/java/com/amazonaws/athena/connectors/udfs/AthenaUDFHandler.java) no GitHub, consulte a página [Amazon Athena UDF Connector](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-udfs) (Conector de UDF do Amazon Athena). # Criar e implantar uma UDF com o Lambda Para criar uma UDF personalizada, crie uma nova classe Java ao estender a classe `UserDefinedFunctionHandler`. O código-fonte para [UserDefinedFunctionHandler.java](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-federation-sdk/src/main/java/com/amazonaws/athena/connector/lambda/handlers/UserDefinedFunctionHandler.java) no SDK está disponível no GitHub no [repositório](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) awslabs/aws-athena-query-federation/athena-federation-sdk, junto com um [exemplo de implementações de UDF](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-udfs) que você pode analisar e modificar para criar uma UDF personalizada. As etapas nessa seção demonstram a criação e compilação de um arquivo Jar da UDF usando [Apache Maven](https://maven.apache.org/index.html) da linha de comando e uma implantação. Execute as etapas a seguir para criar uma UDF personalizada para o Athena usando o Maven 1. [Clonar o SDK e preparar o ambiente de desenvolvimento](#udf-create-install-sdk-prep-environment) 1. [Criar um projeto Maven](#create-maven-project) 1. [Adicionar dependências e plugins ao projeto Maven](#udf-add-maven-dependencies) 1. [Escrever código Java para UDFs](#udf-write-java) 1. [Compilar o arquivo JAR](#udf-create-package-jar) 1. [Implantar o JAR no AWS Lambda](#udf-create-deploy) ## Clonar o SDK e preparar o ambiente de desenvolvimento Antes de começar, certifique-se de que o git esteja instalado no sistema usando `sudo yum install git -y`. **Como instalar o Query Federation SDK da AWS** + Digite o seguinte na linha de comando para clonar o repositório do SDK. Este repositório inclui o SDK, exemplos e um conjunto de conectores de fonte de dados. Para obter mais informações sobre conectores de fonte de dados, consulte [Usar a consulta federada do Amazon Athena](federated-queries.md). ``` git clone https://github.com/awslabs/aws-athena-query-federation.git ``` **Como instalar pré-requisitos para este procedimento** Se você trabalha em uma máquina de desenvolvimento que já tem o Apache Maven, a AWS CLI e a ferramenta de compilação do AWS Serverless Application Model instalados, pode ignorar esta etapa. 1. Na raiz do diretório `aws-athena-query-federation` criado ao executar a clonagem, execute o script [prepare\$1dev\$1env.sh](https://github.com/awslabs/aws-athena-query-federation/blob/master/tools/prepare_dev_env.sh) que prepara o ambiente de desenvolvimento. 1. Atualize o shell para fornecer novas variáveis criadas pelo processo de instalação ou reinicie a sessão do terminal. ``` source ~/.profile ``` **Importante** Se você ignorar essa etapa, receberá erros posteriormente sobre a AWS CLI ou a ferramenta de compilação do AWS SAM não conseguir publicar a função do Lambda. ## Criar um projeto Maven Execute o seguinte comando para criar o projeto Maven. Substitua *groupId* pelo ID exclusivo da organização e substitua *my-athena-udf* pelo nome do aplicativo. Para obter mais informações, consulte [Como criar meu primeiro projeto Maven?](https://maven.apache.org/guides/getting-started/index.html#How_do_I_make_my_first_Maven_project) na documentação Apache Maven. ``` mvn -B archetype:generate \ -DarchetypeGroupId=org.apache.maven.archetypes \ -DgroupId=groupId \ -DartifactId=my-athena-udfs ``` ## Adicionar dependências e plugins ao projeto Maven Adicione as configurações a seguir ao arquivo `pom.xml` do projeto Maven. Para ver um exemplo, consulte o arquivo [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/pom.xml) no GitHub. ``` 2022.47.1 com.amazonaws aws-athena-federation-sdk ${aws-athena-federation-sdk.version} org.apache.maven.plugins maven-shade-plugin 3.2.1 false *:* META-INF/*.SF META-INF/*.DSA META-INF/*.RSA package shade ``` ## Escrever código Java para UDFs Crie uma nova classe ao estender [UserDefinedFunctionHandler.java](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-federation-sdk/src/main/java/com/amazonaws/athena/connector/lambda/handlers/UserDefinedFunctionHandler.java). Escreva as UDFs dentro da classe. No exemplo a seguir, dois métodos Java para UDFs, `compress()` e `decompress()`, são criados dentro da classe `MyUserDefinedFunctions`. ``` *package *com.mycompany.athena.udfs; public class MyUserDefinedFunctions extends UserDefinedFunctionHandler { private static final String SOURCE_TYPE = "MyCompany"; public MyUserDefinedFunctions() { super(SOURCE_TYPE); } /** * Compresses a valid UTF-8 String using the zlib compression library. * Encodes bytes with Base64 encoding scheme. * * @param input the String to be compressed * @return the compressed String */ public String compress(String input) { byte[] inputBytes = input.getBytes(StandardCharsets.UTF_8); // create compressor Deflater compressor = new Deflater(); compressor.setInput(inputBytes); compressor.finish(); // compress bytes to output stream byte[] buffer = new byte[4096]; ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream(inputBytes.length); while (!compressor.finished()) { int bytes = compressor.deflate(buffer); byteArrayOutputStream.write(buffer, 0, bytes); } try { byteArrayOutputStream.close(); } catch (IOException e) { throw new RuntimeException("Failed to close ByteArrayOutputStream", e); } // return encoded string byte[] compressedBytes = byteArrayOutputStream.toByteArray(); return Base64.getEncoder().encodeToString(compressedBytes); } /** * Decompresses a valid String that has been compressed using the zlib compression library. * Decodes bytes with Base64 decoding scheme. * * @param input the String to be decompressed * @return the decompressed String */ public String decompress(String input) { byte[] inputBytes = Base64.getDecoder().decode((input)); // create decompressor Inflater decompressor = new Inflater(); decompressor.setInput(inputBytes, 0, inputBytes.length); // decompress bytes to output stream byte[] buffer = new byte[4096]; ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream(inputBytes.length); try { while (!decompressor.finished()) { int bytes = decompressor.inflate(buffer); if (bytes == 0 && decompressor.needsInput()) { throw new DataFormatException("Input is truncated"); } byteArrayOutputStream.write(buffer, 0, bytes); } } catch (DataFormatException e) { throw new RuntimeException("Failed to decompress string", e); } try { byteArrayOutputStream.close(); } catch (IOException e) { throw new RuntimeException("Failed to close ByteArrayOutputStream", e); } // return decoded string byte[] decompressedBytes = byteArrayOutputStream.toByteArray(); return new String(decompressedBytes, StandardCharsets.UTF_8); } } ``` ## Compilar o arquivo JAR Execute `mvn clean install` para compilar o projeto. Após a compilação com êxito, um arquivo JAR é criado na pasta `target` do projeto nomeado como `artifactId-version.jar`, no qual *artifactId* é o nome fornecido por você no projeto Maven, por exemplo, `my-athena-udfs`. ## Implantar o JAR no AWS Lambda Você tem duas opções para implantar o código no Lambda: + Implantar usando AWS Serverless Application Repository (recomendado) + Criar uma função do Lambda do arquivo JAR ### Opção 1: implantar no AWS Serverless Application Repository Ao implantar o arquivo JAR no AWS Serverless Application Repository, você cria um arquivo YAML de modelo do AWS SAM que representa a arquitetura do aplicativo. Em seguida, você especifica esse arquivo YAML e um bucket do Amazon S3 no qual os artefatos da aplicação são carregados e disponibilizados para o AWS Serverless Application Repository. O procedimento abaixo usa o script [publish.sh](https://github.com/awslabs/aws-athena-query-federation/blob/master/tools/publish.sh) localizado no diretório `athena-query-federation/tools` do Athena Query Federation SDK clonado anteriormente. Para obter mais informações e conhecer os requisitos, consulte [Publicar aplicações](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverlessrepo-publishing-applications.html) no *Guia do desenvolvedor do AWS Serverless Application Repository*, [Conceitos de modelo do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-basics.html) no *Guia do desenvolvedor do AWS Serverless Application Model* e [Publicar aplicações com tecnologia sem servidor usando a CLI do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-publishing-applications.html). O exemplo a seguir demonstra parâmetros em um arquivo YAML. Adicione parâmetros similares ao arquivo YAML e salve-o no diretório de projetos. Consulte [athena-udf.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/athena-udfs.yaml) no GitHub para ver o exemplo completo. ``` Transform: 'AWS::Serverless-2016-10-31' Metadata: 'AWS::ServerlessRepo::Application': Name: MyApplicationName Description: 'The description I write for my application' Author: 'Author Name' Labels: - athena-federation SemanticVersion: 1.0.0 Parameters: LambdaFunctionName: Description: 'The name of the Lambda function that will contain your UDFs.' Type: String LambdaTimeout: Description: 'Maximum Lambda invocation runtime in seconds. (min 1 - 900 max)' Default: 900 Type: Number LambdaMemory: Description: 'Lambda memory in MB (min 128 - 3008 max).' Default: 3008 Type: Number Resources: ConnectorConfig: Type: 'AWS::Serverless::Function' Properties: FunctionName: !Ref LambdaFunctionName Handler: "full.path.to.your.handler. For example, com.amazonaws.athena.connectors.udfs.MyUDFHandler" CodeUri: "Relative path to your JAR file. For example, ./target/athena-udfs-1.0.jar" Description: "My description of the UDFs that this Lambda function enables." Runtime: java8 Timeout: !Ref LambdaTimeout MemorySize: !Ref LambdaMemory ``` Copie o script `publish.sh` para o diretório de projetos no qual você salvou o arquivo YAML e execute o comando: ``` ./publish.sh MyS3Location MyYamlFile ``` Por exemplo, se o local do bucket for `s3://amzn-s3-demo-bucket/mysarapps/athenaudf` e o arquivo YAML for salvo como `my-athena-udfs.yaml`: ``` ./publish.sh amzn-s3-demo-bucket/mysarapps/athenaudf my-athena-udfs ``` **Como criar uma função do Lambda** 1. Abra o console do Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/), escolha **Create function** (Criar função) e selecione **Browse serverless app repository** (Procurar repositório de aplicações sem servidor) 1. Selecione **Private applications (Aplicativos privados)**, localize o aplicativo na lista ou procure usando palavras-chave e selecione-o. 1. Verifique, forneça detalhes do aplicativo e selecione **Deploy (Implantar).** Agora você pode usar os nomes dos métodos definidos no arquivo JAR da função do Lambda como UDFs no Athena. ### Opção 2: criar uma função do Lambda diretamente Você também pode criar uma função do Lambda diretamente usando o console ou a AWS CLI. O exemplo a seguir demonstra o uso do comando da CLI `create-function` do Lambda. ``` aws lambda create-function \ --function-name MyLambdaFunctionName \ --runtime java8 \ --role arn:aws:iam::1234567890123:role/my_lambda_role \ --handler com.mycompany.athena.udfs.MyUserDefinedFunctions \ --timeout 900 \ --zip-file fileb://./target/my-athena-udfs-1.0-SNAPSHOT.jar ``` # Consulta entre regiões O Athena oferece suporte à consulta de dados do Amazon S3 em uma Região da AWS diferente da região na qual você está usando o Athena. A consulta entre regiões pode ser uma boa opção quando não é prático ou permitido mover dados, ou quando você deseja consultar dados em várias regiões. Mesmo que o Athena não esteja disponível em uma determinada região, será possível consultar os dados nela a partir de outra região na qual o Athena esteja disponível. Para consultar dados em uma região, sua conta deve estar habilitada nessa região, mesmo que os dados do Amazon S3 não pertençam à sua conta. Para algumas regiões, como Leste dos EUA (Ohio), seu acesso à região é habilitado automaticamente quando sua conta é criada. Outras regiões exigem a opção de inclusão (status opt-in) da conta antes que você possa usá-la. Para obter a lista de regiões que exigem o status opt-in, consulte [Regiões disponíveis](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions) no *Guia do usuário do Amazon EC2*. Para obter instruções específicas sobre como optar por uma região, consulte [Gerenciar regiões da AWS](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html) no *Referência geral da Amazon Web Services*. ## Considerações e limitações + **Permissões de acesso a dados**: para consultar com êxito dados do Amazon S3 no Athena entre regiões, sua conta deve ter permissões para ler os dados. Se os dados que você deseja consultar pertencerem a outra conta, essa outra conta deverá lhe conceder acesso ao local do Amazon S3 que contém os dados. + **Cobranças de transferência de dados**: aplicam-se cobranças de transferência de dados do Amazon S3 para consultas entre regiões. A execução de uma consulta pode fazer com que mais dados sejam transferidos do que o tamanho do conjunto de dados. É recomendável que você comece testando suas consultas em um subconjunto de dados e analisando os custos no [AWS Cost Explorer](https://aws.amazon.com/aws-cost-management/aws-cost-explorer/). + **AWS Glue**: você pode usar o AWS Glue entre regiões. Podem ser aplicadas cobranças adicionais para tráfego do AWS Glue entre regiões. Para obter mais informações, consulte [Criar conexões do AWS Glue entre contas e entre regiões](https://aws.amazon.com/blogs/big-data/create-cross-account-and-cross-region-aws-glue-connections/) no *AWS Big Data Blog*. + **Opções de criptografia do Amazon S3**: há suporte para as opções de criptografia SSE-S3 e SSE-KMS nas consultas entre regiões. Não há suporte para CSE-KMS. Para obter mais informações, consulte [Opções de criptografia permitidas do Amazon S3](encryption.md#encryption-options-S3-and-Athena). + **Consultas federadas**: não há suporte para o uso de consultas federadas em Regiões da AWS. Desde que as condições acima sejam atendidas, você pode criar uma tabela do Athena que aponte para o valor `LOCATION` especificado e consultar os dados de forma transparente. Não é necessária nenhuma sintaxe especial. Para obter mais informações sobre criação de tabelas, consulte [Criar tabelas no Athena](creating-tables.md). # Consultar o AWS Glue Data Catalog Como o AWS Glue Data Catalog é usado por muitos Serviços da AWS como repositório central de metadados, você pode consultar metadados do catálogo de dados. Para fazer isso, use as consultas SQL no Athena. Você pode usar o Athena para consultar os metadados do catálogo do AWS Glue, como bancos de dados, tabelas, partições e colunas. Para acessar os metadados do catálogo do AWS Glue, consulte o banco de dados `information_schema` no backend do Athena. As consultas de exemplo neste tópico mostram como usar o Athena para consultar os metadados do catálogo do AWS Glue em casos de uso comuns. ## Considerações e limitações + Em vez de consultar o banco de dados `information_schema`, é possível usar [comandos DDL](ddl-reference.md) individuais do Apache Hive para extrair informações de metadados para bancos de dados, tabelas, exibições, partições e colunas específicos do Athena. No entanto, a saída está em um formato não tabular. + As consultas de `information_schema` apresentam melhor performance se você tiver uma quantidade pequena a moderada de metadados do AWS Glue. Pode haver erros se você tiver uma grande quantidade de metadados. + Não é possível usar `CREATE VIEW` para criar uma exibição no banco de dados `information_schema`. **Topics** + [Considerações e limitações](#querying-glue-catalog-considerations-limitations) + [Listar bancos de dados e pesquisar em um banco de dados especificado](querying-glue-catalog-querying-available-databases-including-rdbms.md) + [Listar tabelas em um banco de dados especificado e pesquisar uma tabela por nome](querying-glue-catalog-listing-tables.md) + [Listar partições de uma tabela específica](querying-glue-catalog-listing-partitions.md) + [Listar ou pesquisar colunas de uma tabela ou visualização especificada](querying-glue-catalog-listing-columns.md) + [Listar colunas que tabelas específicas têm em comum](querying-glue-catalog-listing-columns-in-common.md) + [Listar todas as colunas de todas as tabelas](querying-glue-catalog-listing-all-columns-for-all-tables.md) # Listar bancos de dados e pesquisar em um banco de dados especificado Os exemplos nesta seção mostram como listar os bancos de dados em metadados por nome de esquema. **Example – Listar bancos de dados** A consulta de exemplo a seguir lista os bancos de dados da tabela `information_schema.schemata`. ``` SELECT schema_name FROM information_schema.schemata LIMIT 10; ``` A tabela a seguir exibe os resultados do exemplo. **** | | | | --- |--- | | 6 | alb-databas1 | | 7 | alb\$1original\$1cust | | 8 | alblogsdatabase | | 9 | athena\$1db\$1test | | 10 | athena\$1ddl\$1db | **Example – Pesquisar em um banco de dados especificado** Na consulta de exemplo a seguir, `rdspostgresql` é um banco de dados de exemplo. ``` SELECT schema_name FROM information_schema.schemata WHERE schema_name = 'rdspostgresql' ``` A tabela a seguir exibe os resultados do exemplo. **** | | schema\$1name | | --- | --- | | 1 | rdspostgresql | # Listar tabelas em um banco de dados especificado e pesquisar uma tabela por nome Para listar os metadados de tabelas, você pode consultar um esquema ou nome de tabela. **Example – Listar tabelas por esquema** A consulta a seguir lista tabelas que usam o esquema de tabela `rdspostgresql`. ``` SELECT table_schema, table_name, table_type FROM information_schema.tables WHERE table_schema = 'rdspostgresql' ``` A tabela a seguir mostra um exemplo de resultado. **** | | table\$1schema | table\$1name | table\$1type | | --- | --- | --- | --- | | 1 | rdspostgresql | rdspostgresqldb1\$1public\$1account | BASE TABLE | **Example – Pesquisar uma tabela por nome** A consulta a seguir obtém informações de metadados para a tabela `athena1`. ``` SELECT table_schema, table_name, table_type FROM information_schema.tables WHERE table_name = 'athena1' ``` A tabela a seguir mostra um exemplo de resultado. **** | | table\$1schema | table\$1name | table\$1type | | --- | --- | --- | --- | | 1 | padrão | athena1 | BASE TABLE | # Listar partições de uma tabela específica Você pode usar `SHOW PARTITIONS table_name` para listar as partições de uma tabela especificada, como no exemplo a seguir. ``` SHOW PARTITIONS cloudtrail_logs_test2 ``` Você também pode usar uma consulta de metadados `$partitions` para listar os números e os valores de partição de uma tabela específica. **Example — Consultar as partições de uma tabela usando a sintaxe \$1partitions** A consulta de exemplo a seguir lista as partições da tabela `cloudtrail_logs_test2` usando a sintaxe `$partitions`. ``` SELECT * FROM default."cloudtrail_logs_test2$partitions" ORDER BY partition_number ``` A tabela a seguir exibe os resultados do exemplo. **** | | table\$1catalog | table\$1schema | table\$1name | Ano | Mês | Dia | | --- | --- | --- | --- | --- | --- | --- | | 1 | awsdatacatalog | padrão | cloudtrail\$1logs\$1test2 | 2020 | 08 | 10 | | 2 | awsdatacatalog | padrão | cloudtrail\$1logs\$1test2 | 2020 | 08 | 11 | | 3 | awsdatacatalog | padrão | cloudtrail\$1logs\$1test2 | 2020 | 08 | 12 | # Listar ou pesquisar colunas de uma tabela ou visualização especificada Você pode listar todas as colunas de uma tabela, todas as colunas de uma exibição ou pesquisar uma coluna por nome em um banco de dados e tabela especificados. Para listar as colunas, use uma consulta `SELECT *`. Na cláusula `FROM`, especifique `information_schema.columns`. Na cláusula `WHERE`, use `table_schema='database_name'` para especificar o banco de dados e `table_name = 'table_name'` para especificar a tabela ou a visualização que tem as colunas que você deseja listar. **Example – Listar todas as colunas de uma tabela especificada** A consulta de exemplo a seguir lista todas as colunas da tabela `rdspostgresqldb1_public_account`. ``` SELECT * FROM information_schema.columns WHERE table_schema = 'rdspostgresql' AND table_name = 'rdspostgresqldb1_public_account' ``` A tabela a seguir exibe os resultados do exemplo. **** | | table\$1catalog | table\$1schema | table\$1name | column\$1name | ordinal\$1position | column\$1default | is\$1nullable | data\$1type | comment | extra\$1info | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 1 | awsdatacatalog | rdspostgresql | rdspostgresqldb1\$1public\$1account | password | 1 | | SIM | varchar | | | | 2 | awsdatacatalog | rdspostgresql | rdspostgresqldb1\$1public\$1account | user\$1id | 2 | | SIM | integer | | | | 3 | awsdatacatalog | rdspostgresql | rdspostgresqldb1\$1public\$1account | created\$1on | 3 | | SIM | timestamp | | | | 4 | awsdatacatalog | rdspostgresql | rdspostgresqldb1\$1public\$1account | last\$1login | 4 | | SIM | timestamp | | | | 5 | awsdatacatalog | rdspostgresql | rdspostgresqldb1\$1public\$1account | email | 5 | | SIM | varchar | | | | 6 | awsdatacatalog | rdspostgresql | rdspostgresqldb1\$1public\$1account | username | 6 | | SIM | varchar | | | **Example – Listar as colunas de uma visualização especificada** A consulta de exemplo a seguir lista todas as colunas no banco de dados `default` para a exibição `arrayview`. ``` SELECT * FROM information_schema.columns WHERE table_schema = 'default' AND table_name = 'arrayview' ``` A tabela a seguir exibe os resultados do exemplo. **** | | table\$1catalog | table\$1schema | table\$1name | column\$1name | ordinal\$1position | column\$1default | is\$1nullable | data\$1type | comment | extra\$1info | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 1 | awsdatacatalog | padrão | arrayview | searchdate | 1 | | SIM | varchar | | | | 2 | awsdatacatalog | padrão | arrayview | sid | 2 | | SIM | varchar | | | | 3 | awsdatacatalog | padrão | arrayview | btid | 3 | | SIM | varchar | | | | 4 | awsdatacatalog | padrão | arrayview | p | 4 | | SIM | varchar | | | | 5 | awsdatacatalog | padrão | arrayview | infantprice | 5 | | SIM | varchar | | | | 6 | awsdatacatalog | padrão | arrayview | sump | 6 | | SIM | varchar | | | | 7 | awsdatacatalog | padrão | arrayview | journeymaparray | 7 | | SIM | array(varchar) | | | **Example – Pesquisar uma coluna por nome em uma tabela e um banco de dados especificados** A consulta de exemplo a seguir procura metadados para a coluna `sid` na exibição `arrayview` do banco de dados `default`. ``` SELECT * FROM information_schema.columns WHERE table_schema = 'default' AND table_name = 'arrayview' AND column_name='sid' ``` A tabela a seguir mostra um exemplo de resultado. **** | | table\$1catalog | table\$1schema | table\$1name | column\$1name | ordinal\$1position | column\$1default | is\$1nullable | data\$1type | comment | extra\$1info | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 1 | awsdatacatalog | padrão | arrayview | sid | 2 | | SIM | varchar | | | # Listar colunas que tabelas específicas têm em comum É possível listar as colunas que tabelas específicas têm em comum em um banco de dados. + Use a sintaxe `SELECT column_name FROM information_schema.columns`. + Para a cláusula `WHERE`, use a sintaxe `WHERE table_name IN ('table1', 'table2')`. **Example : listagem de colunas comuns para duas tabelas no mesmo banco de dados** O exemplo de consulta a seguir lista as colunas que as tabelas `table1` e `table2` têm em comum. ``` SELECT column_name FROM information_schema.columns WHERE table_name IN ('table1', 'table2') GROUP BY column_name HAVING COUNT(*) > 1; ``` # Listar todas as colunas de todas as tabelas É possível listar todas as colunas de todas as tabelas no `AwsDataCatalog` ou para todas as tabelas em um banco de dados específico no `AwsDataCatalog`. + Para listar todas as colunas de todos os bancos de dados no `AwsDataCatalog`, use a consulta `SELECT * FROM information_schema.columns`. + Para restringir os resultados a um banco de dados específico, use `table_schema='database_name'` na cláusula `WHERE`. **Example — Listagem de todas as colunas de todas as tabelas em um banco de dados específico** A consulta de exemplo a seguir lista todas as colunas de todas as tabelas no banco de dados `webdata`. ``` SELECT * FROM information_schema.columns WHERE table_schema = 'webdata' ``` # Consultar logs do AWS service (Serviço da AWS) Esta seção inclui vários procedimentos para usar o Amazon Athena para consultar conjuntos de dados conhecidos, como os logs do AWS CloudTrail, Amazon CloudFront, Classic Load Balancer, Application Load Balancer, Network Load Balancer, e os logs de fluxo do Amazon VPC. As tarefas nesta seção usam o console do Athena, mas você também pode usar outras ferramentas como o [driver JDBC do Athena](connect-with-jdbc.md), a [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/athena/) ou a [referência de API do Amazon Athena](https://docs.aws.amazon.com/athena/latest/APIReference/). Para obter informações sobre como usar o AWS CloudFormation para criar automaticamente tabelas de log de serviço, partições e consultas de exemplo da AWS service (Serviço da AWS) no Athena, consulte [Automatizar a criação de tabelas de logs de serviço da AWS service (Serviço da AWS) e consultá-las com o Amazon Athena](https://aws.amazon.com/blogs/big-data/automating-aws-service-logs-table-creation-and-querying-them-with-amazon-athena/) no Blog de Big Data da AWS. Para obter informações sobre como usar uma biblioteca Python para o AWS Glue para criar um framework comum de processamento de logs de AWS service (Serviço da AWS) e consultá-los no Athena, consulte [Consulta com facilidade de logs de AWS service (Serviço da AWS) usando o Amazon Athena](https://aws.amazon.com/blogs/big-data/easily-query-aws-service-logs-using-amazon-athena/). Os tópicos nesta seção pressupõem que você configurou as permissões apropriadas para acessar o Athena e o bucket do Amazon S3 no qual os dados a serem consultados devem residir. Para ter mais informações, consulte [Acesso de configuração, administrativo e programático](setting-up.md) e [Conceitos básicos](getting-started.md). **Topics** + [Application Load Balancer](application-load-balancer-logs.md) + [Elastic Load Balancing](elasticloadbalancer-classic-logs.md) + [CloudFront](cloudfront-logs.md) + [CloudTrail](cloudtrail-logs.md) + [Amazon EMR](emr-logs.md) + [Global Accelerator](querying-global-accelerator-flow-logs.md) + [GuardDuty](querying-guardduty.md) + [Network Firewall](querying-network-firewall-logs.md) + [Network Load Balancer](networkloadbalancer-classic-logs.md) + [Route 53](querying-r53-resolver-logs.md) + [Amazon SES](querying-ses-logs.md) + [Amazon VPC](vpc-flow-logs.md) + [AWS WAF](waf-logs.md) # Consultar logs do Application Load Balancer O Application Load Balancer é uma opção de balanceamento de carga do Elastic Load Balancing que habilita a distribuição de tráfego em uma implantação de microsserviços usando contêineres. Consultar logs do Application Load Balancer permite consultar a origem do tráfego, a latência e os bytes transferidos de e para instâncias do Elastic Load Balancing e aplicativos de backend. Para obter mais informações, consulte [Logs de acesso para seu Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-access-logs.html) e [Logs de conexão para seu Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-connection-logs.html) no *Guia do usuário para Application Load Balancers*. ## Pré-requisitos + Habilite o [registro de acesso em log](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-access-logs.html) ou [registro de conexão em log](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-connection-logs.html) para permitir que os logs do Application Load Balancer sejam salvos no seu bucket do Amazon S3. + Um banco de dados para conter a tabela que você criará para o Athena. Para criar um banco de dados, é possível usar o Athena ou o console do AWS Glue. Para obter mais informações, consulte [Criar bancos de dados no Athena](creating-databases.md) neste guia ou [Trabalhar com banco de dados no console do AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/console-databases.html), no *Guia do desenvolvedor do AWS Glue*. **Topics** + [Pré-requisitos](#application-load-balancer-logs-prerequisites) + [Criar a tabela para logs de acesso do ALB](create-alb-access-logs-table.md) + [Criar a tabela para logs de acesso do ALB no Athena com uso da projeção de partições](create-alb-access-logs-table-partition-projection.md) + [Exemplos de consultas para logs de acesso do ALB](query-alb-access-logs-examples.md) + [Criar a tabela para logs de conexão do ALB](create-alb-connection-logs-table.md) + [Criar a tabela para logs de conexão do ALB no Athena com uso da projeção de partições](create-alb-connection-logs-table-partition-projection.md) + [Exemplo de consultas para logs de conexão do ALB](query-alb-connection-logs-examples.md) + [Recursos adicionais](application-load-balancer-logs-additional-resources.md) # Criar a tabela para logs de acesso do ALB 1. Copie e cole a declaração `CREATE TABLE` a seguir em um editor de consulta no console do Athena e modifique-a conforme necessário para seus próprios requisitos de entrada de log. Para obter mais informações sobre os conceitos básicos do Athena, consulte [Conceitos básicos](getting-started.md). Substitua o caminho na cláusula `LOCATION` pela localização da pasta de log de acesso do Amazon S3. Para obter mais informações sobre o local do arquivo de log de acesso, consulte [Arquivos de log de acesso](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-access-logs.html#access-log-file-format) no *Guia do usuário para Application Load Balancers*. Para obter informações sobre cada campo do arquivo de log, consulte [Entradas do log de acesso](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-access-logs.html#access-log-entry-format) no *Guia do usuário para Application Load Balancers*. **nota** A declaração de exemplo `CREATE TABLE` a seguir inclui as colunas `classification`, `classification_reason` e `conn_trace_id` (“ID de rastreabilidade” ou TID) adicionadas recentemente. Para criar uma tabela dos logs de acesso do Application Load Balancer que não contenham essas entradas, remova as colunas correspondentes da instrução `CREATE TABLE` e modifique a expressão regex de acordo. ``` CREATE EXTERNAL TABLE IF NOT EXISTS alb_access_logs ( type string, time string, elb string, client_ip string, client_port int, target_ip string, target_port int, request_processing_time double, target_processing_time double, response_processing_time double, elb_status_code int, target_status_code string, received_bytes bigint, sent_bytes bigint, request_verb string, request_url string, request_proto string, user_agent string, ssl_cipher string, ssl_protocol string, target_group_arn string, trace_id string, domain_name string, chosen_cert_arn string, matched_rule_priority string, request_creation_time string, actions_executed string, redirect_url string, lambda_error_reason string, target_port_list string, target_status_code_list string, classification string, classification_reason string, conn_trace_id string ) ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.RegexSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1', 'input.regex' = '([^ ]*) ([^ ]*) ([^ ]*) ([^ ]*):([0-9]*) ([^ ]*)[:-]([0-9]*) ([-.0-9]*) ([-.0-9]*) ([-.0-9]*) (|[-0-9]*) (-|[-0-9]*) ([-0-9]*) ([-0-9]*) \"([^ ]*) (.*) (- |[^ ]*)\" \"([^\"]*)\" ([A-Z0-9-_]+) ([A-Za-z0-9.-]*) ([^ ]*) \"([^\"]*)\" \"([^\"]*)\" \"([^\"]*)\" ([-.0-9]*) ([^ ]*) \"([^\"]*)\" \"([^\"]*)\" \"([^ ]*)\" \"([^\\s]+?)\" \"([^\\s]+)\" \"([^ ]*)\" \"([^ ]*)\" ?([^ ]*)? ?( .*)?' ) LOCATION 's3://amzn-s3-demo-bucket/access-log-folder-path/' ``` **nota** Sugerimos que o padrão *`?( .*)?`* no final do parâmetro `input.regex` permaneça sempre em vigor para lidar com futuras entradas de registro, caso novos campos de log do ALB sejam adicionados. 1. Execute a consulta no console do Athena. Depois que a consulta for concluída, o Athena registrará a tabela `alb_access_logs`, preparando os dados dela para você fazer as consultas. # Criar a tabela para logs de acesso do ALB no Athena com uso da projeção de partições Como os logs de acesso do ALB têm uma estrutura conhecida com um esquema de partição que você pode especificar antecipadamente, é possível reduzir o runtime das consultas e automatizar o gerenciamento de partições usando o atributo de projeção de partições do Athena. A projeção de partições adiciona automaticamente novas partições à medida que os dados são adicionados. Isso elimina a necessidade de adicionar manualmente as partições usando `ALTER TABLE ADD PARTITION`. O exemplo de instrução `CREATE TABLE` a seguir usa automaticamente a projeção de partições com base em logs de acesso do ALB a partir de uma data especificada até o dia atual para uma única região da AWS. A instrução é baseada no exemplo da seção anterior, mas adiciona as cláusulas `PARTITIONED BY` e `TBLPROPERTIES` para habilitar a projeção de partições. Nas cláusulas `LOCATION` e `storage.location.template`, substitua os espaços reservados pelos valores que identificam o local do bucket do Amazon S3 dos seus logs de acesso do ABL. Para obter mais informações sobre o local do arquivo de log de acesso, consulte [Arquivos de log de acesso](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-access-logs.html#access-log-file-format) no *Guia do usuário para Application Load Balancers*. Em ‭`projection.day.range`‬, substitua ‭‭*01‭*‬/‭*01‭*‬/*2022* pela data de início que você deseja usar. Depois que você executar a consulta com êxito, poderá consultar a tabela. Você não precisa executar `ALTER TABLE ADD PARTITION` para carregar as partições. Para obter informações sobre cada campo do arquivo de log, consulte [Entradas de log de acesso](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-access-logs.html#access-log-entry-format). ``` CREATE EXTERNAL TABLE IF NOT EXISTS alb_access_logs ( type string, time string, elb string, client_ip string, client_port int, target_ip string, target_port int, request_processing_time double, target_processing_time double, response_processing_time double, elb_status_code int, target_status_code string, received_bytes bigint, sent_bytes bigint, request_verb string, request_url string, request_proto string, user_agent string, ssl_cipher string, ssl_protocol string, target_group_arn string, trace_id string, domain_name string, chosen_cert_arn string, matched_rule_priority string, request_creation_time string, actions_executed string, redirect_url string, lambda_error_reason string, target_port_list string, target_status_code_list string, classification string, classification_reason string, conn_trace_id string ) PARTITIONED BY ( day STRING ) ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.RegexSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1', 'input.regex' = '([^ ]*) ([^ ]*) ([^ ]*) ([^ ]*):([0-9]*) ([^ ]*)[:-]([0-9]*) ([-.0-9]*) ([-.0-9]*) ([-.0-9]*) (|[-0-9]*) (-|[-0-9]*) ([-0-9]*) ([-0-9]*) \"([^ ]*) (.*) (- |[^ ]*)\" \"([^\"]*)\" ([A-Z0-9-_]+) ([A-Za-z0-9.-]*) ([^ ]*) \"([^\"]*)\" \"([^\"]*)\" \"([^\"]*)\" ([-.0-9]*) ([^ ]*) \"([^\"]*)\" \"([^\"]*)\" \"([^ ]*)\" \"([^\\s]+?)\" \"([^\\s]+)\" \"([^ ]*)\" \"([^ ]*)\" ?([^ ]*)? ?( .*)?' ) LOCATION 's3://amzn-s3-demo-bucket/AWSLogs//elasticloadbalancing//' TBLPROPERTIES ( "projection.enabled" = "true", "projection.day.type" = "date", "projection.day.range" = "2022/01/01,NOW", "projection.day.format" = "yyyy/MM/dd", "projection.day.interval" = "1", "projection.day.interval.unit" = "DAYS", "storage.location.template" = "s3://amzn-s3-demo-bucket/AWSLogs//elasticloadbalancing//${day}" ) ``` Para obter mais informações sobre projeção de partições, consulte [Usar projeção de partições com o Amazon Athena](partition-projection.md). **nota** Sugerimos que o padrão *?( .\$1)?* no final do parâmetro `input.regex` permaneça sempre aplicado para lidar com futuras entradas de log, caso novos campos de log do ALB sejam adicionados. # Exemplos de consultas para logs de acesso do ALB A consulta a seguir conta o número de solicitações HTTP GET recebidas pelo load balancer agrupadas pelo endereço IP do cliente: ``` SELECT COUNT(request_verb) AS count, request_verb, client_ip FROM alb_access_logs GROUP BY request_verb, client_ip LIMIT 100; ``` Outra consulta mostra os URLs visitados por usuários do navegador Safari: ``` SELECT request_url FROM alb_access_logs WHERE user_agent LIKE '%Safari%' LIMIT 10; ``` A consulta a seguir mostra registros que têm valores de código de status ELB maiores ou iguais a 500. ``` SELECT * FROM alb_access_logs WHERE elb_status_code >= 500 ``` O exemplo a seguir mostra como analisar os registros por `datetime`: ``` SELECT client_ip, sum(received_bytes) FROM alb_access_logs WHERE parse_datetime(time,'yyyy-MM-dd''T''HH:mm:ss.SSSSSS''Z') BETWEEN parse_datetime('2018-05-30-12:00:00','yyyy-MM-dd-HH:mm:ss') AND parse_datetime('2018-05-31-00:00:00','yyyy-MM-dd-HH:mm:ss') GROUP BY client_ip; ``` O exemplo a seguir consulta a tabela que usa projeção de partição para todos os logs de acesso do ALB a partir do dia especificado. ``` SELECT * FROM alb_access_logs WHERE day = '2022/02/12' ``` # Criar a tabela para logs de conexão do ALB 1. Copie e cole o exemplo de declaração `CREATE TABLE` a seguir em um editor de consulta no console do Athena e modifique-a conforme necessário para seus próprios requisitos de entrada de log. Para obter mais informações sobre os conceitos básicos do Athena, consulte [Conceitos básicos](getting-started.md). Substitua o caminho na cláusula `LOCATION` pela localização da pasta de log de conexão do Amazon S3. Para obter mais informações sobre o local do arquivo de log de conexão, consulte [Arquivos de log de conexão](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-connection-logs.html#connection-log-file-format) no *Guia do usuário para Application Load Balancers*. Para obter informações sobre cada campo do arquivo de log, consulte [Entradas de log de conexão](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-connection-logs.html#connection-log-entry-format). ``` CREATE EXTERNAL TABLE IF NOT EXISTS alb_connection_logs ( time string, client_ip string, client_port int, listener_port int, tls_protocol string, tls_cipher string, tls_handshake_latency double, leaf_client_cert_subject string, leaf_client_cert_validity string, leaf_client_cert_serial_number string, tls_verify_status string, conn_trace_id string ) ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.RegexSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1', 'input.regex' = '([^ ]*) ([^ ]*) ([0-9]*) ([0-9]*) ([A-Za-z0-9.-]*) ([^ ]*) ([-.0-9]*) \"([^\"]*)\" ([^ ]*) ([^ ]*) ([^ ]*) ?([^ ]*)?( .*)?' ) LOCATION 's3://amzn-s3-demo-bucket/connection-log-folder-path/' ``` 1. Execute a consulta no console do Athena. Depois que a consulta for concluída, o Athena registrará a tabela `alb_connection_logs`, preparando os dados dela para você fazer as consultas. # Criar a tabela para logs de conexão do ALB no Athena com uso da projeção de partições Como os logs de conexão do ALB têm uma estrutura conhecida com um esquema de partição que você pode especificar antecipadamente, é possível reduzir o runtime das consultas e automatizar o gerenciamento de partições usando o atributo de projeção de partições do Athena. A projeção de partições adiciona automaticamente novas partições à medida que os dados são adicionados. Isso elimina a necessidade de adicionar manualmente as partições usando `ALTER TABLE ADD PARTITION`. O exemplo de instrução `CREATE TABLE` a seguir usa automaticamente a projeção de partições com base em logs de conexão do ALB a partir de uma data especificada até o dia atual para uma única região da AWS. A instrução é baseada no exemplo da seção anterior, mas adiciona as cláusulas `PARTITIONED BY` e `TBLPROPERTIES` para habilitar a projeção de partições. Nas cláusulas `LOCATION` e `storage.location.template`, substitua os espaços reservados pelos valores que identificam o local do bucket do Amazon S3 dos seus logs de conexão do ABL. Para obter mais informações sobre o local do arquivo de log de conexão, consulte [Arquivos de log de conexão](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-connection-logs.html#connection-log-file-format) no *Guia do usuário para Application Load Balancers*. Em ‭`projection.day.range`‬, substitua ‭*01‭*‬/‭*01‭*/‬*2023* pela data de início que você deseja usar. Depois que você executar a consulta com êxito, poderá consultar a tabela. Você não precisa executar `ALTER TABLE ADD PARTITION` para carregar as partições. Para obter informações sobre cada campo do arquivo de log, consulte [Entradas de log de conexão](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-connection-logs.html#connection-log-entry-format). ``` CREATE EXTERNAL TABLE IF NOT EXISTS alb_connection_logs ( time string, client_ip string, client_port int, listener_port int, tls_protocol string, tls_cipher string, tls_handshake_latency double, leaf_client_cert_subject string, leaf_client_cert_validity string, leaf_client_cert_serial_number string, tls_verify_status string, conn_trace_id string ) PARTITIONED BY ( day STRING ) ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.RegexSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1', 'input.regex' = '([^ ]*) ([^ ]*) ([0-9]*) ([0-9]*) ([A-Za-z0-9.-]*) ([^ ]*) ([-.0-9]*) \"([^\"]*)\" ([^ ]*) ([^ ]*) ([^ ]*) ?([^ ]*)?( .*)?' ) LOCATION 's3://amzn-s3-demo-bucket/AWSLogs//elasticloadbalancing//' TBLPROPERTIES ( "projection.enabled" = "true", "projection.day.type" = "date", "projection.day.range" = "2023/01/01,NOW", "projection.day.format" = "yyyy/MM/dd", "projection.day.interval" = "1", "projection.day.interval.unit" = "DAYS", "storage.location.template" = "s3://amzn-s3-demo-bucket/AWSLogs//elasticloadbalancing//${day}" ) ``` Para obter mais informações sobre projeção de partições, consulte [Usar projeção de partições com o Amazon Athena](partition-projection.md). # Exemplo de consultas para logs de conexão do ALB A consulta a seguir conta as ocorrências nas quais o valor de `tls_verify_status` não foi `'Success'`, agrupadas por endereço IP do cliente: ``` SELECT DISTINCT client_ip, count() AS count FROM alb_connection_logs WHERE tls_verify_status != 'Success' GROUP BY client_ip ORDER BY count() DESC; ``` A consulta a seguir pesquisa ocorrências nas quais o valor de `tls_handshake_latency` foi superior a 2 segundos no intervalo de tempo especificado: ``` SELECT * FROM alb_connection_logs WHERE ( parse_datetime(time, 'yyyy-MM-dd''T''HH:mm:ss.SSSSSS''Z') BETWEEN parse_datetime('2024-01-01-00:00:00', 'yyyy-MM-dd-HH:mm:ss') AND parse_datetime('2024-03-20-00:00:00', 'yyyy-MM-dd-HH:mm:ss') ) AND (tls_handshake_latency >= 2.0); ``` # Recursos adicionais Para obter mais informações sobre o uso de logs do ALB, consulte os recursos a seguir. + [Como analisar os logs de acesso do meu Application Load Balancer usando o Amazon Athena](https://repost.aws/knowledge-center/athena-analyze-access-logs) no *Centro de Conhecimentos da AWS*. + Para obter informações sobre códigos de status HTTP do Elastic Load Balancing, consulte [Solução de problemas em Application Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-troubleshooting.html) no *Guia do usuário para Application Load Balancers*. + [Catalogue e analise os logs do Application Load Balancer com mais eficiência com classificadores personalizados AWS Glue e Amazon Athena](https://aws.amazon.com/blogs/big-data/catalog-and-analyze-application-load-balancer-logs-more-efficiently-with-aws-glue-custom-classifiers-and-amazon-athena/) no *Blog de Big Data da AWS*. # Consulta a logs do Classic Load Balancer Consulte os logs do Classic Load Balancer para analisar e saber os padrões do tráfego que entra e sai das instâncias e das aplicações de backend do Elastic Load Balancing. Você pode ver a origem do tráfego, da latência e dos bytes que foram transferidos. Antes de analisar os logs do Elastic Load Balancing, configure-os para que sejam salvos no bucket de destino do Amazon S3. Para obter mais informações, consulte [Habilitar os logs de acesso do seu Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/enable-access-logs.html). **Para criar a tabela de logs do Elastic Load Balancing** 1. Copie e cole a instrução DDL a seguir no console do Athena. Verifique a [sintaxe ](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/access-log-collection.html#access-log-entry-format) dos registros de log do Elastic Load Balancing. Pode ser necessário atualizar a consulta a seguir para incluir as colunas e a sintaxe Regex para a versão mais recente do registro. ``` CREATE EXTERNAL TABLE IF NOT EXISTS elb_logs ( timestamp string, elb_name string, request_ip string, request_port int, backend_ip string, backend_port int, request_processing_time double, backend_processing_time double, client_response_time double, elb_response_code string, backend_response_code string, received_bytes bigint, sent_bytes bigint, request_verb string, url string, protocol string, user_agent string, ssl_cipher string, ssl_protocol string ) ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.RegexSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1', 'input.regex' = '([^ ]*) ([^ ]*) ([^ ]*):([0-9]*) ([^ ]*)[:-]([0-9]*) ([-.0-9]*) ([-.0-9]*) ([-.0-9]*) (|[-0-9]*) (-|[-0-9]*) ([-0-9]*) ([-0-9]*) \\\"([^ ]*) ([^ ]*) (- |[^ ]*)\\\" (\"[^\"]*\") ([A-Z0-9-]+) ([A-Za-z0-9.-]*)$' ) LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/AWS_account_ID/elasticloadbalancing/'; ``` 1. Modifique o bucket `LOCATION` do Amazon S3 para especificar o destino dos logs do Elastic Load Balancing. 1. Execute a consulta no console do Athena. Depois que a consulta for concluída, o Athena registrará a tabela `elb_logs`, preparando os dados dela para as consultas. Para obter mais informações, consulte [Consultas de exemplo](#query-elb-classic-example). ## Consultas de exemplo Use uma consulta semelhante à consulta do exemplo a seguir. Ele lista os servidores de aplicativos de backend que retornaram um código de resposta de erro `4XX` ou `5XX`. Use o operador `LIMIT` para limitar o número de logs a serem consultados por vez. ``` SELECT timestamp, elb_name, backend_ip, backend_response_code FROM elb_logs WHERE backend_response_code LIKE '4%' OR backend_response_code LIKE '5%' LIMIT 100; ``` Use uma consulta subsequente para somar o tempo de resposta de todas as transações agrupadas por endereço IP de backend e nome da instância do Elastic Load Balancing. ``` SELECT sum(backend_processing_time) AS total_ms, elb_name, backend_ip FROM elb_logs WHERE backend_ip <> '' GROUP BY backend_ip, elb_name LIMIT 100; ``` Para obter mais informações, consulte [Analyzing data in S3 using Athena](https://aws.amazon.com/blogs/big-data/analyzing-data-in-s3-using-amazon-athena/) (Analisar dados no S3 usando o Athena). # Consultar logs do Amazon CloudFront Você pode configurar o CDN do Amazon CloudFront para exportar os logs de acesso de distribuição da Web para o Amazon Simple Storage Service. Use esses logs para explorar os padrões de navegação dos usuários nas propriedades da Web processadas pelo CloudFront. Antes de começar a consultar os logs, habilite o log de acesso de distribuições da Web de acordo com a sua distribuição preferida do CloudFront. Para obter informações, consulte [Logs de acesso](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/AccessLogs.html) no *Guia do desenvolvedor do Amazon CloudFront*. Anote o bucket do Amazon S3 no qual salva esses logs. **Topics** + [Criação de uma tabela para os logs padrão do CloudFront (legado)](create-cloudfront-table-standard-logs.md) + [Criação de uma tabela para os logs do CloudFront no Athena usando particionamento manual com JSON](create-cloudfront-table-manual-json.md) + [Criação de uma tabela para os logs do CloudFront no Athena usando particionamento manual com Parquet](create-cloudfront-table-manual-parquet.md) + [Criação de uma tabela para os logs do CloudFront no Athena usando projeção de particionamento com JSON](create-cloudfront-table-partition-json.md) + [Criação de uma tabela para os logs do CloudFront no Athena usando projeção de particionamento com Parquet](create-cloudfront-table-partition-parquet.md) + [Criar uma tabela para logs em tempo real do CloudFront](create-cloudfront-table-real-time-logs.md) + [Recursos adicionais](cloudfront-logs-additional-resources.md) # Criação de uma tabela para os logs padrão do CloudFront (legado) **nota** O procedimento a seguir funciona para os logs de acesso de distribuição da Web no CloudFront. Ele não se aplica a logs de streaming de distribuições RTMP. **Para criar uma tabela para campos de arquivo de log padrão do CloudFront** 1. Copie e cole o exemplo de instrução DDL a seguir no editor de consultas no console do Athena. O exemplo de instrução usa os campos do arquivo de log documentados na seção [Campos de arquivo de log padrão](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/AccessLogs.html#BasicDistributionFileFormat) do *Guia do usuário do Amazon CloudFront.* Modifique o `LOCATION` para o bucket do Amazon S3 que armazena seus logs. Para obter informações sobre como usar o editor de consultas, acesse [Conceitos básicos](getting-started.md). Essa consulta especifica `ROW FORMAT DELIMITED` e `FIELDS TERMINATED BY '\t'` para indicar que os campos são delimitados por caracteres de tabulação. Para `ROW FORMAT DELIMITED`, o Athena usa o [LazySimpleSerDe](lazy-simple-serde.md) por padrão. A coluna `date` é escapada com acentos graves (`) porque se trata de uma palavra reservada no Athena. Para mais informações, consulte [Escapar palavras-chave reservadas em consultas](reserved-words.md). ``` CREATE EXTERNAL TABLE IF NOT EXISTS cloudfront_standard_logs ( `date` DATE, time STRING, x_edge_location STRING, sc_bytes BIGINT, c_ip STRING, cs_method STRING, cs_host STRING, cs_uri_stem STRING, sc_status INT, cs_referrer STRING, cs_user_agent STRING, cs_uri_query STRING, cs_cookie STRING, x_edge_result_type STRING, x_edge_request_id STRING, x_host_header STRING, cs_protocol STRING, cs_bytes BIGINT, time_taken FLOAT, x_forwarded_for STRING, ssl_protocol STRING, ssl_cipher STRING, x_edge_response_result_type STRING, cs_protocol_version STRING, fle_status STRING, fle_encrypted_fields INT, c_port INT, time_to_first_byte FLOAT, x_edge_detailed_result_type STRING, sc_content_type STRING, sc_content_len BIGINT, sc_range_start BIGINT, sc_range_end BIGINT ) ROW FORMAT DELIMITED FIELDS TERMINATED BY '\t' LOCATION 's3://amzn-s3-demo-bucket/' TBLPROPERTIES ( 'skip.header.line.count'='2' ) ``` 1. Execute a consulta no console do Athena. Depois que a consulta for concluída, o Athena registrará a tabela `cloudfront_standard_logs`, preparando os dados dela para você fazer as consultas. ## Consultas de exemplo A consulta a seguir adiciona o número de bytes processados pelo CloudFront entre 9 e 11 de junho de 2018. Coloque o nome da coluna de data entre aspas duplas porque se trata de uma palavra reservada. ``` SELECT SUM(bytes) AS total_bytes FROM cloudfront_standard_logs WHERE "date" BETWEEN DATE '2018-06-09' AND DATE '2018-06-11' LIMIT 100; ``` Para eliminar linhas duplicadas (por exemplo, linhas vazias duplicadas) dos resultados da consulta, é possível usar a instrução `SELECT DISTINCT`, conforme o exemplo a seguir. ``` SELECT DISTINCT * FROM cloudfront_standard_logs LIMIT 10; ``` # Criação de uma tabela para os logs do CloudFront no Athena usando particionamento manual com JSON **Para criar uma tabela para os campos do arquivo de log padrão do CloudFront usando o formato JSON** 1. Copie e cole o exemplo de instrução DDL a seguir no editor de consultas no console do Athena. O exemplo de instrução usa os campos do arquivo de log documentados na seção [Campos de arquivo de log padrão](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/AccessLogs.html#BasicDistributionFileFormat) do *Guia do usuário do Amazon CloudFront.* Modifique o `LOCATION` para o bucket do Amazon S3 que armazena seus logs. Essa consulta usa o OpenX JSON SerDe com as propriedades de SerDe apresentadas a seguir para realizar a leitura dos campos em JSON corretamente no Athena. ``` CREATE EXTERNAL TABLE `cf_logs_manual_partition_json`( `date` string , `time` string , `x-edge-location` string , `sc-bytes` string , `c-ip` string , `cs-method` string , `cs(host)` string , `cs-uri-stem` string , `sc-status` string , `cs(referer)` string , `cs(user-agent)` string , `cs-uri-query` string , `cs(cookie)` string , `x-edge-result-type` string , `x-edge-request-id` string , `x-host-header` string , `cs-protocol` string , `cs-bytes` string , `time-taken` string , `x-forwarded-for` string , `ssl-protocol` string , `ssl-cipher` string , `x-edge-response-result-type` string , `cs-protocol-version` string , `fle-status` string , `fle-encrypted-fields` string , `c-port` string , `time-to-first-byte` string , `x-edge-detailed-result-type` string , `sc-content-type` string , `sc-content-len` string , `sc-range-start` string , `sc-range-end` string ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ( 'paths'='c-ip,c-port,cs(Cookie),cs(Host),cs(Referer),cs(User-Agent),cs-bytes,cs-method,cs-protocol,cs-protocol-version,cs-uri-query,cs-uri-stem,date,fle-encrypted-fields,fle-status,sc-bytes,sc-content-len,sc-content-type,sc-range-end,sc-range-start,sc-status,ssl-cipher,ssl-protocol,time,time-taken,time-to-first-byte,x-edge-detailed-result-type,x-edge-location,x-edge-request-id,x-edge-response-result-type,x-edge-result-type,x-forwarded-for,x-host-header') STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/' ``` 1. Execute a consulta no console do Athena. Depois que a consulta for concluída, o Athena registrará a tabela `cf_logs_manual_partition_json`, preparando os dados dela para você fazer as consultas. ## Consultas de exemplo A consulta apresentada a seguir soma a quantidade de bytes fornecidos pelo CloudFront no dia 15 de janeiro de 2025. ``` SELECT sum(cast("sc-bytes" as BIGINT)) as sc FROM cf_logs_manual_partition_json WHERE "date"='2025-01-15' ``` Para eliminar linhas duplicadas (por exemplo, linhas vazias duplicadas) dos resultados da consulta, é possível usar a instrução `SELECT DISTINCT`, conforme o exemplo a seguir. ``` SELECT DISTINCT * FROM cf_logs_manual_partition_json ``` # Criação de uma tabela para os logs do CloudFront no Athena usando particionamento manual com Parquet **Para criar uma tabela para os campos do arquivo de log padrão do CloudFront usando o formato Parquet** 1. Copie e cole o exemplo de instrução DDL a seguir no editor de consultas no console do Athena. O exemplo de instrução usa os campos do arquivo de log documentados na seção [Campos de arquivo de log padrão](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/AccessLogs.html#BasicDistributionFileFormat) do *Guia do usuário do Amazon CloudFront.* Essa consulta usa o ParquetHiveSerDe com as propriedades de SerDe apresentadas a seguir para realizar a leitura dos campos em Parquet corretamente no Athena. ``` CREATE EXTERNAL TABLE `cf_logs_manual_partition_parquet`( `date` string, `time` string, `x_edge_location` string, `sc_bytes` string, `c_ip` string, `cs_method` string, `cs_host` string, `cs_uri_stem` string, `sc_status` string, `cs_referer` string, `cs_user_agent` string, `cs_uri_query` string, `cs_cookie` string, `x_edge_result_type` string, `x_edge_request_id` string, `x_host_header` string, `cs_protocol` string, `cs_bytes` string, `time_taken` string, `x_forwarded_for` string, `ssl_protocol` string, `ssl_cipher` string, `x_edge_response_result_type` string, `cs_protocol_version` string, `fle_status` string, `fle_encrypted_fields` string, `c_port` string, `time_to_first_byte` string, `x_edge_detailed_result_type` string, `sc_content_type` string, `sc_content_len` string, `sc_range_start` string, `sc_range_end` string) ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe' STORED AS INPUTFORMAT 'org.apache.hadoop.hive.ql.io.parquet.MapredParquetInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.parquet.MapredParquetOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/' ``` 1. Execute a consulta no console do Athena. Depois que a consulta for concluída, o Athena registrará a tabela `cf_logs_manual_partition_parquet`, preparando os dados dela para você fazer as consultas. ## Consultas de exemplo A consulta apresentada a seguir soma a quantidade de bytes fornecidos pelo CloudFront no dia 19 de janeiro de 2025. ``` SELECT sum(cast("sc_bytes" as BIGINT)) as sc FROM cf_logs_manual_partition_parquet WHERE "date"='2025-01-19' ``` Para eliminar linhas duplicadas (por exemplo, linhas vazias duplicadas) dos resultados da consulta, é possível usar a instrução `SELECT DISTINCT`, conforme o exemplo a seguir. ``` SELECT DISTINCT * FROM cf_logs_manual_partition_parquet ``` # Criação de uma tabela para os logs do CloudFront no Athena usando projeção de particionamento com JSON Você pode reduzir o runtime da consulta e automatizar o gerenciamento de particionamento com o recurso de projeção de particionamento do Athena. A projeção de partições adiciona automaticamente novas partições à medida que os dados são adicionados. Isso elimina a necessidade de adicionar manualmente as partições usando `ALTER TABLE ADD PARTITION`. A instrução CREATE TABLE, apresentada como exemplo a seguir, usa automaticamente a projeção de particionamento nos logs do CloudFront usando uma distribuição do CloudFront especificada até o momento, para uma única Região da AWS. Depois que você executar a consulta com êxito, poderá consultar a tabela. ``` CREATE EXTERNAL TABLE `cloudfront_logs_pp`( `date` string, `time` string, `x-edge-location` string, `sc-bytes` string, `c-ip` string, `cs-method` string, `cs(host)` string, `cs-uri-stem` string, `sc-status` string, `cs(referer)` string, `cs(user-agent)` string, `cs-uri-query` string, `cs(cookie)` string, `x-edge-result-type` string, `x-edge-request-id` string, `x-host-header` string, `cs-protocol` string, `cs-bytes` string, `time-taken` string, `x-forwarded-for` string, `ssl-protocol` string, `ssl-cipher` string, `x-edge-response-result-type` string, `cs-protocol-version` string, `fle-status` string, `fle-encrypted-fields` string, `c-port` string, `time-to-first-byte` string, `x-edge-detailed-result-type` string, `sc-content-type` string, `sc-content-len` string, `sc-range-start` string, `sc-range-end` string) PARTITIONED BY( distributionid string, year int, month int, day int, hour int ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ( 'paths'='c-ip,c-port,cs(Cookie),cs(Host),cs(Referer),cs(User-Agent),cs-bytes,cs-method,cs-protocol,cs-protocol-version,cs-uri-query,cs-uri-stem,date,fle-encrypted-fields,fle-status,sc-bytes,sc-content-len,sc-content-type,sc-range-end,sc-range-start,sc-status,ssl-cipher,ssl-protocol,time,time-taken,time-to-first-byte,x-edge-detailed-result-type,x-edge-location,x-edge-request-id,x-edge-response-result-type,x-edge-result-type,x-forwarded-for,x-host-header') STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/AWS_ACCOUNT_ID/CloudFront/' TBLPROPERTIES ( 'projection.distributionid.type'='enum', 'projection.distributionid.values'='E2Oxxxxxxxxxxx', 'projection.day.range'='01,31', 'projection.day.type'='integer', 'projection.day.digits'='2', 'projection.enabled'='true', 'projection.month.range'='01,12', 'projection.month.type'='integer', 'projection.month.digits'='2', 'projection.year.range'='2025,2026', 'projection.year.type'='integer', 'projection.hour.range'='00,23', 'projection.hour.type'='integer', 'projection.hour.digits'='2', 'storage.location.template'='s3://amzn-s3-demo-bucket/AWSLogs/AWS_ACCOUNT_ID/CloudFront/${distributionid}/${year}/${month}/${day}/${hour}/') ``` A seguir, apresentamos algumas considerações sobre as propriedades usadas no exemplo anterior. + **Nome da tabela**: o nome da tabela, *`cloudfront_logs_pp`*, pode ser alterado. Você pode alterá-lo para qualquer nome de sua preferência. + **Localização**: Altere `s3://amzn-s3-demo-bucket/AWSLogs/AWS_ACCOUNT_ID/` para direcionar para o seu bucket do Amazon S3. + **IDs de distribuição**: para `projection.distributionid.values`, você pode especificar vários IDs de distribuição, separando-os por vírgulas. Por exemplo, **, **. + **Intervalo de anos**: em `projection.year.range`, você pode definir o intervalo de anos com base nos seus dados. Por exemplo, você pode ajustá-lo para qualquer período, como 2025 e *2025*, *2026*. **nota** Incluir partições vazias, como aquelas para datas futuras (por exemplo, 2025 a 2040), pode impactar a performance das consultas. No entanto, a projeção de partições foi projetada para lidar efetivamente com datas futuras. Para manter uma performance ideal, garanta que as partições sejam gerenciadas de forma estratégica e evite criar partições vazias excessivas sempre que possível. + **Modelo de local de armazenamento**: Você deve garantir que o modelo `storage.location.template` seja atualizado corretamente com base na estrutura de particionamento do CloudFront e no caminho do S3 apresentados a seguir. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/create-cloudfront-table-partition-json.html) Após confirmar que a estrutura de particionamento do CloudFront e a estrutura do S3 correspondem aos padrões necessários, atualize o modelo `storage.location.template` da seguinte forma: ``` 'storage.location.template'='s3://amzn-s3-demo-bucket/AWSLogs/account_id/CloudFront/${distributionid}/folder2/${year}/${month}/${day}/${hour}/folder3/' ``` **nota** A configuração adequada do modelo `storage.location.template` é essencial para assegurar o armazenamento e a recuperação adequados dos dados. # Criação de uma tabela para os logs do CloudFront no Athena usando projeção de particionamento com Parquet A instrução CREATE TABLE, apresentada como exemplo a seguir, usa automaticamente a projeção de particionamento nos logs do CloudFront em Parquet usando uma distribuição do CloudFront especificada até o momento, para uma única Região da AWS. Depois que você executar a consulta com êxito, poderá consultar a tabela. ``` CREATE EXTERNAL TABLE `cloudfront_logs_parquet_pp`( `date` string, `time` string, `x_edge_location` string, `sc_bytes` string, `c_ip` string, `cs_method` string, `cs_host` string, `cs_uri_stem` string, `sc_status` string, `cs_referer` string, `cs_user_agent` string, `cs_uri_query` string, `cs_cookie` string, `x_edge_result_type` string, `x_edge_request_id` string, `x_host_header` string, `cs_protocol` string, `cs_bytes` string, `time_taken` string, `x_forwarded_for` string, `ssl_protocol` string, `ssl_cipher` string, `x_edge_response_result_type` string, `cs_protocol_version` string, `fle_status` string, `fle_encrypted_fields` string, `c_port` string, `time_to_first_byte` string, `x_edge_detailed_result_type` string, `sc_content_type` string, `sc_content_len` string, `sc_range_start` string, `sc_range_end` string) PARTITIONED BY( distributionid string, year int, month int, day int, hour int ) ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe' STORED AS INPUTFORMAT 'org.apache.hadoop.hive.ql.io.parquet.MapredParquetInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.parquet.MapredParquetOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/AWS_ACCOUNT_ID/CloudFront/' TBLPROPERTIES ( 'projection.distributionid.type'='enum', 'projection.distributionid.values'='E3OK0LPUNWWO3', 'projection.day.range'='01,31', 'projection.day.type'='integer', 'projection.day.digits'='2', 'projection.enabled'='true', 'projection.month.range'='01,12', 'projection.month.type'='integer', 'projection.month.digits'='2', 'projection.year.range'='2019,2025', 'projection.year.type'='integer', 'projection.hour.range'='01,12', 'projection.hour.type'='integer', 'projection.hour.digits'='2', 'storage.location.template'='s3://amzn-s3-demo-bucket/AWSLogs/AWS_ACCOUNT_ID/CloudFront/${distributionid}/${year}/${month}/${day}/${hour}/') ``` A seguir, apresentamos algumas considerações sobre as propriedades usadas no exemplo anterior. + **Nome da tabela**: o nome da tabela, *`cloudfront_logs_pp`*, pode ser alterado. Você pode alterá-lo para qualquer nome de sua preferência. + **Localização**: Altere `s3://amzn-s3-demo-bucket/AWSLogs/AWS_ACCOUNT_ID/` para direcionar para o seu bucket do Amazon S3. + **IDs de distribuição**: para `projection.distributionid.values`, você pode especificar vários IDs de distribuição, separando-os por vírgulas. Por exemplo, **, **. + **Intervalo de anos**: em `projection.year.range`, você pode definir o intervalo de anos com base nos seus dados. Por exemplo, você pode ajustá-lo para qualquer período, como *2025* e *2026*. **nota** Incluir partições vazias, como aquelas para datas futuras (por exemplo, 2025 a 2040), pode impactar a performance das consultas. No entanto, a projeção de partições foi projetada para lidar efetivamente com datas futuras. Para manter uma performance ideal, garanta que as partições sejam gerenciadas de forma estratégica e evite criar partições vazias excessivas sempre que possível. + **Modelo de local de armazenamento**: Você deve garantir que o modelo `storage.location.template` seja atualizado corretamente com base na estrutura de particionamento do CloudFront e no caminho do S3 apresentados a seguir. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/create-cloudfront-table-partition-parquet.html) Após confirmar que a estrutura de particionamento do CloudFront e a estrutura do S3 correspondem aos padrões necessários, atualize o modelo `storage.location.template` da seguinte forma: ``` 'storage.location.template'='s3://amzn-s3-demo-bucket/AWSLogs/account_id/CloudFront/${distributionid}/folder2/${year}/${month}/${day}/${hour}/folder3/' ``` **nota** A configuração adequada do modelo `storage.location.template` é essencial para assegurar o armazenamento e a recuperação adequados dos dados. # Criar uma tabela para logs em tempo real do CloudFront **Para criar uma tabela para campos de arquivo de log em tempo real do CloudFront** 1. Copie e cole o exemplo de instrução DDL a seguir no editor de consultas no console do Athena. O exemplo de instrução usa os campos do arquivo de log documentados na seção [Logs em tempo real](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/real-time-logs.html) do *Guia do usuário do Amazon CloudFront*. Modifique o `LOCATION` para o bucket do Amazon S3 que armazena seus logs. Para obter informações sobre como usar o editor de consultas, acesse [Conceitos básicos](getting-started.md). Essa consulta especifica `ROW FORMAT DELIMITED` e `FIELDS TERMINATED BY '\t'` para indicar que os campos são delimitados por caracteres de tabulação. Para `ROW FORMAT DELIMITED`, o Athena usa o [LazySimpleSerDe](lazy-simple-serde.md) por padrão. A coluna `timestamp` é escapada com acentos graves (`) porque se trata de uma palavra reservada no Athena. Para mais informações, consulte [Escapar palavras-chave reservadas em consultas](reserved-words.md). O exemplo a seguir contém todos os campos disponíveis. Você pode comentar ou remover campos que não sejam necessários. ``` CREATE EXTERNAL TABLE IF NOT EXISTS cloudfront_real_time_logs ( `timestamp` STRING, c_ip STRING, time_to_first_byte BIGINT, sc_status BIGINT, sc_bytes BIGINT, cs_method STRING, cs_protocol STRING, cs_host STRING, cs_uri_stem STRING, cs_bytes BIGINT, x_edge_location STRING, x_edge_request_id STRING, x_host_header STRING, time_taken BIGINT, cs_protocol_version STRING, c_ip_version STRING, cs_user_agent STRING, cs_referer STRING, cs_cookie STRING, cs_uri_query STRING, x_edge_response_result_type STRING, x_forwarded_for STRING, ssl_protocol STRING, ssl_cipher STRING, x_edge_result_type STRING, fle_encrypted_fields STRING, fle_status STRING, sc_content_type STRING, sc_content_len BIGINT, sc_range_start STRING, sc_range_end STRING, c_port BIGINT, x_edge_detailed_result_type STRING, c_country STRING, cs_accept_encoding STRING, cs_accept STRING, cache_behavior_path_pattern STRING, cs_headers STRING, cs_header_names STRING, cs_headers_count BIGINT, primary_distribution_id STRING, primary_distribution_dns_name STRING, origin_fbl STRING, origin_lbl STRING, asn STRING ) ROW FORMAT DELIMITED FIELDS TERMINATED BY '\t' LOCATION 's3://amzn-s3-demo-bucket/' TBLPROPERTIES ( 'skip.header.line.count'='2' ) ``` 1. Execute a consulta no console do Athena. Depois que a consulta for concluída, o Athena registrará a tabela `cloudfront_real_time_logs`, preparando os dados dela para você fazer as consultas. # Recursos adicionais Para obter mais informações sobre como usar o Athena para consultar os logs do CloudFront, leia as publicações do [blog sobre big data da AWS](https://aws.amazon.com/blogs/big-data/) a seguir. [Consulte facilmente os logs de AWS service (Serviço da AWS) usando o Amazon Athena](https://aws.amazon.com/blogs/big-data/easily-query-aws-service-logs-using-amazon-athena/) de 29 de maio de 2019 (em inglês). [Analise seus logs de acesso do Amazon CloudFront em grande escala](https://aws.amazon.com/blogs/big-data/analyze-your-amazon-cloudfront-access-logs-at-scale/) (21 de dezembro de 2018). [Construa uma arquitetura serverless para analisar os logs de acesso do Amazon CloudFront usando AWS Lambda, Amazon Athena e o Amazon Managed Service for Apache Flink](https://aws.amazon.com/blogs/big-data/build-a-serverless-architecture-to-analyze-amazon-cloudfront-access-logs-using-aws-lambda-amazon-athena-and-amazon-kinesis-analytics/) (26 de maio de 2017). # Consultar logs do AWS CloudTrail O AWS CloudTrail é um serviço que registra chamadas de API da AWS e eventos de contas da Amazon Web Services. Os logs do CloudTrail incluem detalhes sobre todas as chamadas de API feitas para seus Serviços da AWS, incluindo o console. O CloudTrail gera arquivos de log criptografados e os armazena no Amazon S3. Para saber mais, consulte o [Guia do usuário do AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html). **nota** Se você quiser realizar consultas SQL nas informações de eventos do CloudTrail entre contas, regiões e datas, considere usar o CloudTrail Lake. O CloudTrail Lake é uma alternativa da AWS à criação de trilhas que agregam informações de uma empresa em um único armazenamento pesquisável de dados de eventos. Em vez de usar o armazenamento de bucket do Amazon S3, ele armazena eventos em um data lake, o que permite consultas mais avançadas e rápidas. Você pode usá-lo para criar consultas SQL que pesquisem eventos em organizações, regiões e em períodos temporais personalizados. Como você executa consultas do CloudTrail Lake diretamente no console do CloudTrail, o uso do CloudTrail Lake não requer o Athena. Para obter mais informações, consulte a Documentação do [CloudTrail Lake](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html). O uso do Athena com os logs do CloudTrail é uma ótima maneira de melhorar a análise das atividades da AWS service (Serviço da AWS). Por exemplo, é possível usar consultas para identificar tendências e isolar ainda mais a atividade por atributos, como endereço IP de origem ou usuário. Uma aplicação comum é usar os logs do CloudTrail para analisar a segurança e a compatibilidade das atividades operacionais. Para obter um exemplo detalhado, consulte a publicação no Blog de Big Data da AWS, [Análise de segurança, conformidade e atividades operacionais usando o AWS CloudTrail e o Amazon Athena](https://aws.amazon.com/blogs/big-data/aws-cloudtrail-and-amazon-athena-dive-deep-to-analyze-security-compliance-and-operational-activity/). Você pode usar o Athena para consultar esses arquivos de log diretamente no Amazon S3 especificando o `LOCATION` dos arquivos de log. É possível fazer isso de duas formas: + Criando tabelas para arquivos de log do CloudTrail diretamente no console do CloudTrail. + Criando tabelas manualmente para arquivos de log do CloudTrail no console do Athena. **Topics** + [Noções básicas de logs do CloudTrail e tabelas do Athena](create-cloudtrail-table-understanding.md) + [Usar o console do CloudTrail para criar uma tabela do Athena com logs do CloudTrail](create-cloudtrail-table-ct.md) + [Criar uma tabela de logs do CloudTrail no Athena usando particionamento manual](create-cloudtrail-table.md) + [Criar uma tabela para uma trilha em toda a organização usando particionamento manual](create-cloudtrail-table-org-wide-trail.md) + [Criar a tabela para logs do CloudTrail no Athena usando a projeção de partições](create-cloudtrail-table-partition-projection.md) + [Exemplo de consultas de log do CloudTrail](query-examples-cloudtrail-logs.md) # Noções básicas de logs do CloudTrail e tabelas do Athena Antes de começar a criar tabelas, você deve conhecer melhor o CloudTrail e saber como ele armazena os dados. Isso pode ajudar a criar as tabelas necessárias, tanto pelo console do CloudTrail quanto pelo Athena. O CloudTrail salva logs como arquivos de texto JSON no formato compactado gzip (`*.json.gz`). O local dos arquivos de log depende de como você configura as trilhas, da Região da AWS ou das regiões onde você está registrando, além de outros fatores. Para obter mais informações de onde os logs são armazenados, da estrutura JSON e do conteúdo do arquivo de registro, consulte os seguintes tópicos no [Manual do usuário do AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html): + [Encontrar os arquivos de log do CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-find-log-files.html) + [Exemplos de arquivos de log do CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-log-file-examples.html) + [Conteúdo do registro do CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-record-contents.html) + [Referência de eventos do CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference.html) Para coletar e salvar os logs no Amazon S3, habilite o CloudTrail no Console de gerenciamento da AWS. Para obter mais informações, consulte [Criar uma trilha](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-a-trail-using-the-console-first-time.html) no *Guia do usuário do AWS CloudTrail*. # Usar o console do CloudTrail para criar uma tabela do Athena com logs do CloudTrail Você pode criar uma tabela do Athena não particionada para consultar logs do CloudTrail diretamente no console do CloudTrail. A criação de uma tabela do Athena pelo console do CloudTrail requer que você esteja conectado com um perfil que tenha permissões suficientes para criar tabelas no Athena. **nota** Não é possível usar o console do CloudTrail para criar uma tabela do Athena para logs de trilha da organização. Em vez disso, crie a tabela manualmente usando o console do Athena para que você possa especificar o local correto de armazenamento. Para obter informações sobre trilhas de organização, consulte [Criar uma trilha para uma organização](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-trail-organization.html) no *Manual do usuário do AWS CloudTrail*. + Para obter informações sobre como configurar permissões para o Athena, consulte [Acesso de configuração, administrativo e programático](setting-up.md). + Para obter informações sobre como criar uma tabela com partições, consulte [Criar uma tabela de logs do CloudTrail no Athena usando particionamento manual](create-cloudtrail-table.md). **Para criar uma tabela do Athena para uma trilha do CloudTrail no console do CloudTrail** 1. Abra o console do CloudTrail em [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/). 1. No painel de navegação, selecione **Event history (Histórico de eventos)**. 1. Escolha **Create Athena table** (Criar tabela do Athena). ![\[Escolher Create Athena table\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/cloudtrail-logs-create-athena-table.png) 1. Em **Storage location** (Local de armazenamento), use a seta para baixo para selecionar o bucket do Amazon S3 onde os arquivos de log estão armazenados para a trilha que será consultada. **nota** Para localizar o nome do bucket associado a uma trilha, escolha **Trails** (Trilhas) no painel de navegação do CloudTrail e visualize a coluna **S3 bucket** (Bucket do S3) da trilha. Para ver o local do bucket do Amazon S3, escolha o link do bucket na coluna **S3 bucket** (Bucket do S3). O console do Amazon S3 é aberto no local do bucket do CloudTrail. 1. Escolha **Criar tabela**. A tabela é criada com um nome padrão que inclui o nome do bucket do Amazon S3. # Criar uma tabela de logs do CloudTrail no Athena usando particionamento manual É possível criar manualmente tabelas de arquivos de log do CloudTrail no console do Athena e executar consultas no Athena. **Para criar uma tabela do Athena para uma trilha do CloudTrail no console do Athena** 1. Copie e cole a instrução DDL a seguir em um editor de consultas do console do Athena e modifique-a de acordo com seus requisitos. Observe que, como os arquivos de log do CloudTrail não são um rastreamento de pilha ordenada de chamadas de API públicas, os campos dos arquivos de log não aparecem em nenhuma ordem específica. ``` CREATE EXTERNAL TABLE cloudtrail_logs ( eventversion STRING, useridentity STRUCT< type:STRING, principalid:STRING, arn:STRING, accountid:STRING, invokedby:STRING, accesskeyid:STRING, username:STRING, onbehalfof: STRUCT< userid: STRING, identitystorearn: STRING>, sessioncontext:STRUCT< attributes:STRUCT< mfaauthenticated:STRING, creationdate:STRING>, sessionissuer:STRUCT< type:STRING, principalid:STRING, arn:STRING, accountid:STRING, username:STRING>, ec2roledelivery:string, webidfederationdata: STRUCT< federatedprovider: STRING, attributes: map> > >, eventtime STRING, eventsource STRING, eventname STRING, awsregion STRING, sourceipaddress STRING, useragent STRING, errorcode STRING, errormessage STRING, requestparameters STRING, responseelements STRING, additionaleventdata STRING, requestid STRING, eventid STRING, resources ARRAY>, eventtype STRING, apiversion STRING, readonly STRING, recipientaccountid STRING, serviceeventdetails STRING, sharedeventid STRING, vpcendpointid STRING, vpcendpointaccountid STRING, eventcategory STRING, addendum STRUCT< reason:STRING, updatedfields:STRING, originalrequestid:STRING, originaleventid:STRING>, sessioncredentialfromconsole STRING, edgedevicedetails STRING, tlsdetails STRUCT< tlsversion:STRING, ciphersuite:STRING, clientprovidedhostheader:STRING> ) PARTITIONED BY (region string, year string, month string, day string) ROW FORMAT SERDE 'org.apache.hive.hcatalog.data.JsonSerDe' STORED AS INPUTFORMAT 'com.amazon.emr.cloudtrail.CloudTrailInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/Account_ID/'; ``` **nota** Sugerimos usar o `org.apache.hive.hcatalog.data.JsonSerDe` exibido no exemplo. Embora exista um `com.amazon.emr.hive.serde.CloudTrailSerde`, no momento ele não processa alguns dos campos mais recentes do CloudTrail. 1. (Opcional) Remova quaisquer campos não obrigatórios para a tabela. Se for necessário ler somente um determinado conjunto de colunas, sua definição de tabela poderá excluir as outras colunas. 1. Modifique `s3://amzn-s3-demo-bucket/AWSLogs/Account_ID/` para apontar para o bucket do Amazon S3 que contém os dados de log que você deseja consultar. O exemplo usa um valor `LOCATION` de logs para uma determinada conta, mas você pode usar o grau de especificidade adequado ao aplicativo. Por exemplo: + Para analisar dados de várias contas, você pode reverter o especificador `LOCATION` para indicar todos os `AWSLogs` usando `LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/'`. + Para analisar dados de uma data, conta e região específica, use `LOCATION 's3://amzn-s3-demo-bucket/123456789012/CloudTrail/us-east-1/2016/03/14/'.` + Para analisar dados de atividade de rede em vez de eventos de gerenciamento, substitua `/CloudTrail/` na cláusula `LOCATION` por `/CloudTrail-NetworkActivity/`. O uso do nível mais alto na hierarquia de objetos proporciona maior flexibilidade ao consultar usando o Athena. 1. Verifique se os campos estão listados corretamente. Para obter mais informações sobre a lista completa de campos em um registro do CloudTrail, consulte [Conteúdo do registro do CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-record-contents.html). A declaração de exemplo `CREATE TABLE` na Etapa 1 usa [Hive JSON SerDe](hive-json-serde.md). No exemplo, os campos `requestparameters`, `responseelements` e `additionaleventdata` são listados como tipo `STRING` na consulta, mas são tipos de dados `STRUCT` usados em JSON. Portanto, para obter dados desses campos, use funções `JSON_EXTRACT`. Para obter mais informações, consulte [Extrair dados JSON de strings](extracting-data-from-JSON.md). Para melhorias de performance, o exemplo particiona os dados por Região da AWS, ano, mês e dia. 1. Execute a instrução `CREATE TABLE` no console do Athena. 1. Use o comando [ALTER TABLE ADD PARTITION](alter-table-add-partition.md) a fim de carregar as partições para que você consiga consultá-las, conforme o exemplo a seguir. ``` ALTER TABLE table_name ADD PARTITION (region='us-east-1', year='2019', month='02', day='01') LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/Account_ID/CloudTrail/us-east-1/2019/02/01/' ``` # Criar uma tabela para uma trilha em toda a organização usando particionamento manual Para criar uma tabela para arquivos de log do CloudTrail em toda a organização no Athena, siga as etapas listadas em [Criar uma tabela de logs do CloudTrail no Athena usando particionamento manual](create-cloudtrail-table.md), mas faça as modificações observadas no procedimento a seguir. **Criar uma tabela do Athena para logs do CloudTrail em toda a organização** 1. Na instrução `CREATE TABLE`, modifique a cláusula `LOCATION` para incluir o ID da organização, como no exemplo a seguir: ``` LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/organization_id/' ``` 1. Na cláusula `PARTITIONED BY`, adicione uma entrada para o ID da conta como cadeia de caracteres, como no exemplo a seguir: ``` PARTITIONED BY (account string, region string, year string, month string, day string) ``` O exemplo a seguir mostra o resultado combinado: ``` ... PARTITIONED BY (account string, region string, year string, month string, day string) ROW FORMAT SERDE 'org.apache.hive.hcatalog.data.JsonSerDe' STORED AS INPUTFORMAT 'com.amazon.emr.cloudtrail.CloudTrailInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/organization_id/Account_ID/CloudTrail/' ``` 1. Na instrução `ALTER TABLE`, na cláusula `ADD PARTITION`, inclua o ID da organização, como no exemplo a seguir: ``` ALTER TABLE table_name ADD PARTITION (account='111122223333', region='us-east-1', year='2022', month='08', day='08') ``` 1. Na instrução `ALTER TABLE`, na cláusula `LOCATION`, inclua o ID da organização, o ID da conta e a partição que você deseja adicionar, como no exemplo a seguir: ``` LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/organization_id/Account_ID/CloudTrail/us-east-1/2022/08/08/' ``` No exemplo a seguir, a instrução `ALTER TABLE` mostra o resultado combinado: ``` ALTER TABLE table_name ADD PARTITION (account='111122223333', region='us-east-1', year='2022', month='08', day='08') LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/organization_id/111122223333/CloudTrail/us-east-1/2022/08/08/' ``` Observe que, em uma grande organização, usar esse método para adicionar e manter manualmente uma partição para cada ID de conta da organização pode ser complicado. Nesse cenário, considere usar o CloudTrail Lake em vez do Athena. O CloudTrail Lake oferece as seguintes vantagens: + Agrega automaticamente os logs em toda a organização + Não requer configuração ou manutenção de partições ou de uma tabela do Athena + As consultas são executadas diretamente no console do CloudTrail + Usa uma linguagem de consultas compatível com SQL Para obter mais informações, consulte [Trabalhar com o AWS Lake](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html), no *Guia do usuário do AWS CloudTrail*. # Criar a tabela para logs do CloudTrail no Athena usando a projeção de partições Como os logs do CloudTrail têm uma estrutura conhecida com um esquema de partição que você pode especificar antecipadamente, é possível reduzir o runtime das consultas e automatizar o gerenciamento de partições usando o atributo de projeção de partições do Athena. A projeção de partições adiciona automaticamente novas partições à medida que os dados são adicionados. Isso elimina a necessidade de adicionar manualmente as partições usando `ALTER TABLE ADD PARTITION`. A instrução de exemplo `CREATE TABLE` a seguir usa automaticamente a projeção de partições com base nos logs do CloudTrail a partir de uma data especificada até o dia de hoje para uma única Região da AWS. Nas cláusulas `LOCATION` e `storage.location.template`, substitua os espaços reservados *bucket*, *account-id* e *aws-region* pelos valores idênticos correspondentes. Em ‭`projection.timestamp.range`‬, substitua ‭*2020*/*01*/*01* pela data de início que você deseja usar. Depois que você executar a consulta com êxito, poderá consultar a tabela. Você não precisa executar `ALTER TABLE ADD PARTITION` para carregar as partições. ``` CREATE EXTERNAL TABLE cloudtrail_logs_pp( eventversion STRING, useridentity STRUCT< type: STRING, principalid: STRING, arn: STRING, accountid: STRING, invokedby: STRING, accesskeyid: STRING, username: STRING, onbehalfof: STRUCT< userid: STRING, identitystorearn: STRING>, sessioncontext: STRUCT< attributes: STRUCT< mfaauthenticated: STRING, creationdate: STRING>, sessionissuer: STRUCT< type: STRING, principalid: STRING, arn: STRING, accountid: STRING, username: STRING>, ec2roledelivery:string, webidfederationdata: STRUCT< federatedprovider: STRING, attributes: map> > >, eventtime STRING, eventsource STRING, eventname STRING, awsregion STRING, sourceipaddress STRING, useragent STRING, errorcode STRING, errormessage STRING, requestparameters STRING, responseelements STRING, additionaleventdata STRING, requestid STRING, eventid STRING, readonly STRING, resources ARRAY>, eventtype STRING, apiversion STRING, recipientaccountid STRING, serviceeventdetails STRING, sharedeventid STRING, vpcendpointid STRING, vpcendpointaccountid STRING, eventcategory STRING, addendum STRUCT< reason:STRING, updatedfields:STRING, originalrequestid:STRING, originaleventid:STRING>, sessioncredentialfromconsole STRING, edgedevicedetails STRING, tlsdetails STRUCT< tlsversion:STRING, ciphersuite:STRING, clientprovidedhostheader:STRING> ) PARTITIONED BY ( `timestamp` string) ROW FORMAT SERDE 'org.apache.hive.hcatalog.data.JsonSerDe' STORED AS INPUTFORMAT 'com.amazon.emr.cloudtrail.CloudTrailInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/account-id/CloudTrail/aws-region' TBLPROPERTIES ( 'projection.enabled'='true', 'projection.timestamp.format'='yyyy/MM/dd', 'projection.timestamp.interval'='1', 'projection.timestamp.interval.unit'='DAYS', 'projection.timestamp.range'='2020/01/01,NOW', 'projection.timestamp.type'='date', 'storage.location.template'='s3://amzn-s3-demo-bucket/AWSLogs/account-id/CloudTrail/aws-region/${timestamp}') ``` Para obter mais informações sobre projeção de partições, consulte [Usar projeção de partições com o Amazon Athena](partition-projection.md). # Exemplo de consultas de log do CloudTrail O exemplo a seguir mostra a parte de uma consulta que retorna todas as solicitações anônimas (não assinadas) da tabela criada para os logs de eventos do CloudTrail. Essa consulta seleciona as solicitações em que `useridentity.accountid` são anônimos e `useridentity.arn` não é especificado: ``` SELECT * FROM cloudtrail_logs WHERE eventsource = 's3.amazonaws.com' AND eventname in ('GetObject') AND useridentity.accountid = 'anonymous' AND useridentity.arn IS NULL AND requestparameters LIKE '%[your bucket name ]%'; ``` Para obter mais informações, consulte a publicação no Blog de Big Data da AWS, [Análise de segurança, conformidade e atividades operacionais usando o AWS CloudTrail e o Amazon Athena](https://aws.amazon.com/blogs/big-data/aws-cloudtrail-and-amazon-athena-dive-deep-to-analyze-security-compliance-and-operational-activity/). ## Consulta de campos aninhados nos logs do CloudTrail Como os campos `userIdentity` e `resources` são tipos de dados aninhados, é necessário um tratamento especial para consultá-los. O objeto `userIdentity` consiste em tipos `STRUCT` aninhados. É possível consultá-los usando um ponto para separar os campos, como no seguinte exemplo: ``` SELECT eventsource, eventname, useridentity.sessioncontext.attributes.creationdate, useridentity.sessioncontext.sessionissuer.arn FROM cloudtrail_logs WHERE useridentity.sessioncontext.sessionissuer.arn IS NOT NULL ORDER BY eventsource, eventname LIMIT 10 ``` O campo `resources` é um array de objetos `STRUCT`. Para esses arrays, use `CROSS JOIN UNNEST` para remover o aninhamento do array de modo que você possa consultar seus objetos. O exemplo a seguir retorna todas as linhas em que o ARN do recurso termina com `example/datafile.txt`. Para legibilidade, a função [replace](https://prestodb.io/docs/current/functions/string.html#replace) remove a substring inicial `arn:aws:s3:::` do ARN. ``` SELECT awsregion, replace(unnested.resources_entry.ARN,'arn:aws:s3:::') as s3_resource, eventname, eventtime, useragent FROM cloudtrail_logs t CROSS JOIN UNNEST(t.resources) unnested (resources_entry) WHERE unnested.resources_entry.ARN LIKE '%example/datafile.txt' ORDER BY eventtime ``` Veja a seguir exemplos de consultas de eventos `DeleteBucket`. A consulta extrai do objeto `resources` o nome do bucket e o ID da conta à qual o bucket pertence. ``` SELECT awsregion, replace(unnested.resources_entry.ARN,'arn:aws:s3:::') as deleted_bucket, eventtime AS time_deleted, useridentity.username, unnested.resources_entry.accountid as bucket_acct_id FROM cloudtrail_logs t CROSS JOIN UNNEST(t.resources) unnested (resources_entry) WHERE eventname = 'DeleteBucket' ORDER BY eventtime ``` Para obter mais informações sobre como remover o aninhamento, consulte [Filtrar matrizes](filtering-arrays.md). ## Dicas para consultar logs do CloudTrail Considere o seguinte ao explorar dados do log do CloudTrail: + Antes de consultar os logs, verifique se a tabela de logs tem a mesma aparência da tabela em [Criar uma tabela de logs do CloudTrail no Athena usando particionamento manual](create-cloudtrail-table.md). Se não for a primeira tabela, exclua a tabela existente usando o seguinte comando: `DROP TABLE cloudtrail_logs`. + Depois de ignorar a tabela existente, recrie-a. Para obter mais informações, consulte [Criar uma tabela de logs do CloudTrail no Athena usando particionamento manual](create-cloudtrail-table.md). Verifique se os campos na consulta do Athena estão listados corretamente. Para obter informações sobre a lista completa de campos em um registro do CloudTrail, consulte [Conteúdo do registro do CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-record-contents.html). Se a consulta incluir campos em formatos JSON, como `STRUCT`, extraia dados de JSON. Para obter mais informações, consulte [Extrair dados JSON de strings](extracting-data-from-JSON.md). Algumas sugestões para realizar consultas em sua tabela do CloudTrail: + Comece observando quais usuários do chamaram quais operações da API e de quais endereços IP de origem. + Use a consulta SQL básica a seguir como o modelo. Cole a consulta no console do Athena e execute-a. ``` SELECT useridentity.arn, eventname, sourceipaddress, eventtime FROM cloudtrail_logs LIMIT 100; ``` + Modifique a consulta para explorar ainda mais seus dados. + Para melhorar a performance, inclua a cláusula `LIMIT` para retornar um subconjunto especificado de linhas. # Consulta a logs do Amazon EMR As aplicações do Amazon EMR e de big data executadas no Amazon EMR geram arquivos de log. Os arquivos de log são gravados no [nó primário](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-master-core-task-nodes.html), e você também pode configurar o Amazon EMR para armazená-los automaticamente no Amazon S3. Você pode usar o Amazon Athena para consultar esses logs e identificar eventos e tendências de aplicações e clusters. Para obter mais informações sobre os tipos de arquivos de log no Amazon EMR e como salvá-los no Amazon S3, consulte [View log files](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-manage-view-web-log-files.html) (Exibir arquivos de log) no *Guia de gerenciamento do Amazon EMR*. **Topics** + [Criação e consulta a uma tabela básica baseada em arquivos de log do Amazon EMR](emr-create-table.md) + [Criar e consultar uma tabela particionada baseada nos logs do Amazon EMR](emr-create-table-partitioned.md) # Criação e consulta a uma tabela básica baseada em arquivos de log do Amazon EMR O exemplo a seguir cria uma tabela básica, `myemrlogs`, com base em arquivos de log salvos em `s3://aws-logs-123456789012-us-west-2/elasticmapreduce/j-2ABCDE34F5GH6/elasticmapreduce/`. O local do Amazon S3 usado nos exemplos abaixo reflete o padrão do local predefinido dos logs de um cluster do EMR criado pela conta da Amazon Web Services *123456789012* na região *us-west-2*. Se você usar um local personalizado, o padrão será s3://amzn-s3-demo-bucket/*ClusterID*. Para obter informações sobre a criação de uma tabela particionada para potencialmente aprimorar a performance da consulta e reduzir a transferência de dados, consulte [Criar e consultar uma tabela particionada baseada nos logs do Amazon EMR](emr-create-table-partitioned.md). ``` CREATE EXTERNAL TABLE `myemrlogs`( `data` string COMMENT 'from deserializer') ROW FORMAT DELIMITED FIELDS TERMINATED BY '|' LINES TERMINATED BY '\n' STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://aws-logs-123456789012-us-west-2/elasticmapreduce/j-2ABCDE34F5GH6' ``` ## Consultas de exemplo Os exemplos de consultas a seguir podem ser executados na tabela `myemrlogs` criada pelo exemplo anterior. **Example – Consultar os logs de etapas para ocorrências de ERROR, WARN, INFO, EXCEPTION, FATAL ou DEBUG** ``` SELECT data, "$PATH" FROM "default"."myemrlogs" WHERE regexp_like("$PATH",'s-86URH188Z6B1') AND regexp_like(data, 'ERROR|WARN|INFO|EXCEPTION|FATAL|DEBUG') limit 100; ``` **Example – Consultar um log de instância específico, i-00b3c0a839ece0a9c, para ERROR, WARN, INFO, EXCEPTION, FATAL ou DEBUG** ``` SELECT "data", "$PATH" AS filepath FROM "default"."myemrlogs" WHERE regexp_like("$PATH",'i-00b3c0a839ece0a9c') AND regexp_like("$PATH",'state') AND regexp_like(data, 'ERROR|WARN|INFO|EXCEPTION|FATAL|DEBUG') limit 100; ``` **Example – Consultar os logs da aplicação Presto para ERROR, WARN, INFO, EXCEPTION, FATAL ou DEBUG** ``` SELECT "data", "$PATH" AS filepath FROM "default"."myemrlogs" WHERE regexp_like("$PATH",'presto') AND regexp_like(data, 'ERROR|WARN|INFO|EXCEPTION|FATAL|DEBUG') limit 100; ``` **Example – Consultar os logs da aplicação Namenode para ERROR, WARN, INFO, EXCEPTION, FATAL ou DEBUG** ``` SELECT "data", "$PATH" AS filepath FROM "default"."myemrlogs" WHERE regexp_like("$PATH",'namenode') AND regexp_like(data, 'ERROR|WARN|INFO|EXCEPTION|FATAL|DEBUG') limit 100; ``` **Example – Consultar todos os logs por data e hora para ERROR, WARN, INFO, EXCEPTION, FATAL ou DEBUG** ``` SELECT distinct("$PATH") AS filepath FROM "default"."myemrlogs" WHERE regexp_like("$PATH",'2019-07-23-10') AND regexp_like(data, 'ERROR|WARN|INFO|EXCEPTION|FATAL|DEBUG') limit 100; ``` # Criar e consultar uma tabela particionada baseada nos logs do Amazon EMR Esses exemplos usam o mesmo local de log para criar uma tabela do Athena, mas a tabela é particionada e uma partição é criada para cada local de log. Para obter mais informações, consulte [Particionar dados](partitions.md). A consulta a seguir cria a tabela particionada denominada `mypartitionedemrlogs`: ``` CREATE EXTERNAL TABLE `mypartitionedemrlogs`( `data` string COMMENT 'from deserializer') partitioned by (logtype string) ROW FORMAT DELIMITED FIELDS TERMINATED BY '|' LINES TERMINATED BY '\n' STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://aws-logs-123456789012-us-west-2/elasticmapreduce/j-2ABCDE34F5GH6' ``` Na sequência, as instruções de consulta a seguir criam as partições de tabela com base nos subdiretórios dos tipos diferentes de log que o Amazon EMR cria no Amazon S3: ``` ALTER TABLE mypartitionedemrlogs ADD PARTITION (logtype='containers') LOCATION 's3://aws-logs-123456789012-us-west-2/elasticmapreduce/j-2ABCDE34F5GH6/containers/' ``` ``` ALTER TABLE mypartitionedemrlogs ADD PARTITION (logtype='hadoop-mapreduce') LOCATION 's3://aws-logs-123456789012-us-west-2/elasticmapreduce/j-2ABCDE34F5GH6/hadoop-mapreduce/' ``` ``` ALTER TABLE mypartitionedemrlogs ADD PARTITION (logtype='hadoop-state-pusher') LOCATION 's3://aws-logs-123456789012-us-west-2/elasticmapreduce/j-2ABCDE34F5GH6/hadoop-state-pusher/' ``` ``` ALTER TABLE mypartitionedemrlogs ADD PARTITION (logtype='node') LOCATION 's3://aws-logs-123456789012-us-west-2/elasticmapreduce/j-2ABCDE34F5GH6/node/' ``` ``` ALTER TABLE mypartitionedemrlogs ADD PARTITION (logtype='steps') LOCATION 's3://aws-logs-123456789012-us-west-2/elasticmapreduce/j-2ABCDE34F5GH6/steps/' ``` Depois de criar as partições, você pode executar uma consulta `SHOW PARTITIONS` na tabela para confirmar: ``` SHOW PARTITIONS mypartitionedemrlogs; ``` ## Consultas de exemplo Os exemplos a seguir demonstram que consultas para entradas de log específicas usam a tabela e as partições criadas pelos exemplos acima. **Example – Consultar os logs da aplicação application\$11561661818238\$10002 na partição de contêineres para ERROR ou WARN** ``` SELECT data, "$PATH" FROM "default"."mypartitionedemrlogs" WHERE logtype='containers' AND regexp_like("$PATH",'application_1561661818238_0002') AND regexp_like(data, 'ERROR|WARN') limit 100; ``` **Example – Consultar a partição Hadoop-Mapreduce do trabalho job\$11561661818238\$10004 e as falhas de redução** ``` SELECT data, "$PATH" FROM "default"."mypartitionedemrlogs" WHERE logtype='hadoop-mapreduce' AND regexp_like(data,'job_1561661818238_0004|Failed Reduces') limit 100; ``` **Example – Consultar os logs do Hive na partição do nó em relação ao ID de consulta 056e0609-33e1-4611-956c-7a31b42d2663** ``` SELECT data, "$PATH" FROM "default"."mypartitionedemrlogs" WHERE logtype='node' AND regexp_like("$PATH",'hive') AND regexp_like(data,'056e0609-33e1-4611-956c-7a31b42d2663') limit 100; ``` **Example – Consultar os logs do Resourcemanager na partição do nó em relação à aplicação 1567660019320\$10001\$101\$1000001** ``` SELECT data, "$PATH" FROM "default"."mypartitionedemrlogs" WHERE logtype='node' AND regexp_like(data,'resourcemanager') AND regexp_like(data,'1567660019320_0001_01_000001') limit 100 ``` # Consultar logs de fluxo do AWS Global Accelerator É possível usar o AWS Global Accelerator para criar aceleradoras que direcionam o tráfego de rede para endpoints ideais na rede global da AWS. Para obter mais informações sobre o Global Accelerator, consulte [What is AWS Global Accelerator?](https://docs.aws.amazon.com/global-accelerator/latest/dg/what-is-global-accelerator.html) (O que é o ?). Os logs de fluxo do Global Accelerator permitem que você capture as informações sobre o tráfego de endereço IP que entra e sai das interfaces de rede em suas aceleradoras. Os dados do log de fluxo são publicados no Amazon S3, de onde é possível recuperá-los e visualizá-los. Para obter mais informações, consulte [Flow logs in AWS Global Accelerator](https://docs.aws.amazon.com/global-accelerator/latest/dg/monitoring-global-accelerator.flow-logs.html) (Logs de fluxo do ). É possível usar o Athena para consultar os logs de fluxo do Global Accelerator criando uma tabela que especifica o local deles no Amazon S3. **Para criar a tabela de logs de fluxo do Global Accelerator** 1. Copie e cole a instrução DDL a seguir no console do Athena. Esta consulta especifica *ROW FORMAT DELIMITED* e omite a especificação de um [SerDe](serde-reference.md), o que significa que a consulta usa [`LazySimpleSerDe`](lazy-simple-serde.md). Nesta consulta, os campos terminam com um espaço. ``` CREATE EXTERNAL TABLE IF NOT EXISTS aga_flow_logs ( version string, account string, acceleratorid string, clientip string, clientport int, gip string, gipport int, endpointip string, endpointport int, protocol string, ipaddresstype string, numpackets bigint, numbytes int, starttime int, endtime int, action string, logstatus string, agasourceip string, agasourceport int, endpointregion string, agaregion string, direction string, vpc_id string, reject_reason string ) PARTITIONED BY (dt string) ROW FORMAT DELIMITED FIELDS TERMINATED BY ' ' LOCATION 's3://amzn-s3-demo-bucket/prefix/AWSLogs/account_id/globalaccelerator/region/' TBLPROPERTIES ("skip.header.line.count"="1"); ``` 1. Modifique o valor `LOCATION` para apontar para o bucket do Amazon S3 que contém os dados de log. ``` 's3://amzn-s3-demo-bucket/prefix/AWSLogs/account_id/globalaccelerator/region_code/' ``` 1. Execute a consulta no console do Athena. Depois que a consulta for concluída, o Athena registrará a tabela `aga_flow_logs`, disponibilizando os dados dela para consultas. 1. Crie partições para ler os dados, conforme a consulta de exemplo a seguir. Esta consulta cria uma única partição para uma data especificada. Substitua os espaços reservados por data e local. ``` ALTER TABLE aga_flow_logs ADD PARTITION (dt='YYYY-MM-dd') LOCATION 's3://amzn-s3-demo-bucket/prefix/AWSLogs/account_id/globalaccelerator/region_code/YYYY/MM/dd'; ``` ## Consultas de exemplo para logs de fluxo do AWS Global Accelerator **Example – Listar as solicitações que passam por um local da borda específico** A consulta de exemplo a seguir lista as solicitações que passaram pelo ponto de presença do LHR. Use o operador `LIMIT` para limitar o número de logs a serem consultados por vez. ``` SELECT clientip, agaregion, protocol, action FROM aga_flow_logs WHERE agaregion LIKE 'LHR%' LIMIT 100; ``` **Example – Listar os endereços IP dos endpoints que recebem a maioria das solicitações HTTPS** Para ver quais endereços IP do endpoint estão recebendo o maior número de solicitações HTTPS, use a seguinte consulta. Esta consulta conta o número de pacotes recebidos na porta HTTPS 443, agrupa-os por endereço IP de destino e retorna os 10 principais endereços IP. ``` SELECT SUM(numpackets) AS packetcount, endpointip FROM aga_flow_logs WHERE endpointport = 443 GROUP BY endpointip ORDER BY packetcount DESC LIMIT 10; ``` # Consultar descobertas do Amazon GuardDuty O [Amazon GuardDuty](https://aws.amazon.com/guardduty/) é um serviço de monitoramento de segurança que ajuda a identificar atividades inesperadas e potencialmente mal-intencionadas ou não autorizadas em seu ambiente AWS. Quando detecta atividades inesperadas e potencialmente mal-intencionadas, o GuardDuty gera [descobertas](https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_findings.html) de segurança que você pode exportar para o Amazon S3 para armazenamento e análise. Depois de exportar as descobertas para o Amazon S3, você pode usar o Athena para consultá-las. Este artigo mostra como criar uma tabela no Athena para as descobertas do GuardDuty e consultá-las. Para obter mais informações sobre o Amazon GuardDuty, consulte o [Manual do usuário do Amazon GuardDuty](https://docs.aws.amazon.com/guardduty/latest/ug/). ## Pré-requisitos + Habilite o recurso GuardDuty para exportar as descobertas para o Amazon S3. Para conhecer as etapas, consulte [Exporting findings](https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_exportfindings.html) (Exportar descobertas) no Guia do usuário do Amazon GuardDuty. ## Criar uma tabela no Athena para as descobertas do GuardDuty Para consultar as descobertas do GuardDuty no Athena, crie uma tabela para elas. **Para criar uma tabela no Athena para as descobertas do GuardDuty** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. Copie a instrução DDL a seguir no console do Athena. Modifique os valores em `LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/account-id/GuardDuty/'` para apontar para as descobertas do GuardDuty no Amazon S3. ``` CREATE EXTERNAL TABLE `gd_logs` ( `schemaversion` string, `accountid` string, `region` string, `partition` string, `id` string, `arn` string, `type` string, `resource` string, `service` string, `severity` string, `createdat` string, `updatedat` string, `title` string, `description` string) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/account-id/GuardDuty/' TBLPROPERTIES ('has_encrypted_data'='true') ``` **nota** O SerDe espera que cada documento JSON esteja em uma única linha de texto, sem caracteres de terminação de linha separando os campos no registro. Se o texto JSON estiver formatado para impressão, você poderá receber uma mensagem de erro como HIVE\$1CURSOR\$1ERROR: Row is not a valid JSON Object (HIVE\$1CURSOR\$1ERROR: a linha não é um objeto JSON válido) ou HIVE\$1CURSOR\$1ERROR: JsonParseException: Unexpected end-of-input: expected close marker for OBJECT (HIVE\$1CURSOR\$1ERROR: JSONParseException: Fim de entrada inesperado: marcador de fechamento esperado para OBJECT) quando tentar consultar a tabela após criá-la. Para obter mais informações, consulte [JSON Data Files](https://github.com/rcongiu/Hive-JSON-Serde#json-data-files) na documentação do OpenX SerDe no GitHub. 1. Execute a consulta no console do Athena para registrar a tabela `gd_logs`. Quando a consulta for concluída, as descobertas estarão prontas para serem consultadas no Athena. ## Consultas de exemplo Os exemplos a seguir mostram como consultar as descobertas do GuardDuty no Athena. **Example – Exfiltração de dados de DNS** A consulta a seguir retorna informações sobre as instâncias do Amazon EC2 que podem estar exfiltrando dados por meio das consultas de DNS. ``` SELECT title, severity, type, id AS FindingID, accountid, region, createdat, updatedat, json_extract_scalar(service, '$.count') AS Count, json_extract_scalar(resource, '$.instancedetails.instanceid') AS InstanceID, json_extract_scalar(service, '$.action.actiontype') AS DNS_ActionType, json_extract_scalar(service, '$.action.dnsrequestaction.domain') AS DomainName, json_extract_scalar(service, '$.action.dnsrequestaction.protocol') AS protocol, json_extract_scalar(service, '$.action.dnsrequestaction.blocked') AS blocked FROM gd_logs WHERE type = 'Trojan:EC2/DNSDataExfiltration' ORDER BY severity DESC ``` **Example – Acesso de usuário do IAM não autorizado** A consulta a seguir retorna todos os tipos de descoberta `UnauthorizedAccess:IAMUser` referentes a um principal do IAM de todas as regiões. ``` SELECT title, severity, type, id, accountid, region, createdat, updatedat, json_extract_scalar(service, '$.count') AS Count, json_extract_scalar(resource, '$.accesskeydetails.username') AS IAMPrincipal, json_extract_scalar(service,'$.action.awsapicallaction.api') AS APIActionCalled FROM gd_logs WHERE type LIKE '%UnauthorizedAccess:IAMUser%' ORDER BY severity desc; ``` ## Dicas para consultar descobertas do GuardDuty Ao criar a consulta, mantenha os seguintes pontos em mente. + Para extrair dados de campos JSON aninhados, use as funções `json_extract` ou `json_extract_scalar` do Presto. Para ter mais informações, consulte [Extrair dados JSON de strings](extracting-data-from-JSON.md). + Certifique-se de que todos os caracteres nos campos JSON estejam em minúsculas. + Para obter informações sobre como baixar resultados de consulta, verifique [Baixar arquivos de resultados de consultas via console do Athena](saving-query-results.md). # Consultar logs do AWS Network Firewall AWS Network Firewall é um serviço gerenciado que você pode usar para implantar proteções de rede essenciais em suas instâncias do Amazon Virtual Private Cloud. O AWS Network Firewall funciona em conjunto com o AWS Firewall Manager para que você possa criar políticas com base nas regras do AWS Network Firewall e aplicá-las a suas VPCs e contas de maneira centralizada. Para obter mais informações sobre AWS Network Firewall, consulte [AWS Network Firewall](https://aws.amazon.com/network-firewall/). É possível configurar os logs do AWS Network Firewall para o tráfego que você encaminha para o mecanismo de regras com estado do firewall. Os logs apresentam informações detalhadas sobre o tráfego de rede, incluindo a hora em que o mecanismo com estado recebeu um pacote, os detalhes do pacote e qualquer ação de regra com estado realizada no pacote. Os logs são publicados no destino de logs que você configurou, de onde é possível recuperá-los e visualizá-los. Para obter mais informações, consulte [Registrar o tráfego de rede do AWS Network Firewall](https://docs.aws.amazon.com/network-firewall/latest/developerguide/firewall-logging.html) no *Guia do desenvolvedor do AWS Network Firewall* (em inglês). **Topics** + [Criar e consultar uma tabela para logs de alertas](querying-network-firewall-logs-sample-alert-logs-table.md) + [Criar e consultar uma tabela para logs de fluxo de rede](querying-network-firewall-logs-sample-netflow-logs-table.md) # Criar e consultar uma tabela para logs de alertas 1. Modifique o exemplo de instrução DDL a seguir para se adequar à estrutura do seu log de alertas. Pode ser necessário atualizar a instrução para incluir as colunas da versão mais recente dos logs. Para obter mais informações, consulte [Conteúdo de um log de firewall](https://docs.aws.amazon.com/network-firewall/latest/developerguide/firewall-logging.html#firewall-logging-contents) no *Guia do desenvolvedor do AWS Network Firewall*. ``` CREATE EXTERNAL TABLE network_firewall_alert_logs ( firewall_name string, availability_zone string, event_timestamp string, event struct< timestamp:string, flow_id:bigint, event_type:string, src_ip:string, src_port:int, dest_ip:string, dest_port:int, proto:string, app_proto:string, sni:string, tls_inspected:boolean, tls_error:struct< error_message:string>, revocation_check:struct< leaf_cert_fpr:string, status:string, action:string>, alert:struct< alert_id:string, alert_type:string, action:string, signature_id:int, rev:int, signature:string, category:string, severity:int, rule_name:string, alert_name:string, alert_severity:string, alert_description:string, file_name:string, file_hash:string, packet_capture:string, reference_links:array >, src_country:string, dest_country:string, src_hostname:string, dest_hostname:string, user_agent:string, url:string > ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' LOCATION 's3://amzn-s3-demo-bucket/path_to_alert_logs_folder/'; ``` 1. Modifique a cláusula `LOCATION` para especificar a pasta para seus logs no Amazon S3. 1. Execute sua consulta `CREATE TABLE` no editor de consultas do Athena. Depois que a consulta for concluída, o Athena registrará a tabela `network_firewall_alert_logs`, preparando os dados para os quais ela direciona para as consultas. ## Consulta de exemplo O exemplo de consulta de log de alertas nesta seção filtra os eventos nos quais a inspeção TLS foi realizada e que têm alertas com um nível de severidade de 2 ou superior. A consulta usa aliases para criar cabeçalhos de coluna de saída que mostram o `struct` ao qual a coluna pertence. Por exemplo, o título da coluna do campo `event.alert.category` é `event_alert_category` em vez de apenas`category`. Para personalizar ainda mais os nomes das colunas, você pode modificar os aliases de acordo com suas preferências. Por exemplo, você pode usar sublinhados ou outros separadores para delimitar os nomes de `struct` e os nomes dos campos. Lembre-se de modificar os nomes de colunas e as referências de `struct` com base na definição da tabela e nos campos que você deseja no resultado da consulta. ``` SELECT firewall_name, availability_zone, event_timestamp, event.timestamp AS event_timestamp, event.flow_id AS event_flow_id, event.event_type AS event_type, event.src_ip AS event_src_ip, event.src_port AS event_src_port, event.dest_ip AS event_dest_ip, event.dest_port AS event_dest_port, event.proto AS event_protol, event.app_proto AS event_app_proto, event.sni AS event_sni, event.tls_inspected AS event_tls_inspected, event.tls_error.error_message AS event_tls_error_message, event.revocation_check.leaf_cert_fpr AS event_revocation_leaf_cert, event.revocation_check.status AS event_revocation_check_status, event.revocation_check.action AS event_revocation_check_action, event.alert.alert_id AS event_alert_alert_id, event.alert.alert_type AS event_alert_alert_type, event.alert.action AS event_alert_action, event.alert.signature_id AS event_alert_signature_id, event.alert.rev AS event_alert_rev, event.alert.signature AS event_alert_signature, event.alert.category AS event_alert_category, event.alert.severity AS event_alert_severity, event.alert.rule_name AS event_alert_rule_name, event.alert.alert_name AS event_alert_alert_name, event.alert.alert_severity AS event_alert_alert_severity, event.alert.alert_description AS event_alert_alert_description, event.alert.file_name AS event_alert_file_name, event.alert.file_hash AS event_alert_file_hash, event.alert.packet_capture AS event_alert_packet_capture, event.alert.reference_links AS event_alert_reference_links, event.src_country AS event_src_country, event.dest_country AS event_dest_country, event.src_hostname AS event_src_hostname, event.dest_hostname AS event_dest_hostname, event.user_agent AS event_user_agent, event.url AS event_url FROM network_firewall_alert_logs WHERE event.alert.severity >= 2 AND event.tls_inspected = true LIMIT 10; ``` # Criar e consultar uma tabela para logs de fluxo de rede 1. Modifique o exemplo de instrução DDL a seguir para se adequar à estrutura do seu log de fluxo de redes. Pode ser necessário atualizar a instrução para incluir as colunas da versão mais recente dos logs. Para obter mais informações, consulte [Conteúdo de um log de firewall](https://docs.aws.amazon.com/network-firewall/latest/developerguide/firewall-logging.html#firewall-logging-contents) no *Guia do desenvolvedor do AWS Network Firewall*. ``` CREATE EXTERNAL TABLE network_firewall_netflow_logs ( firewall_name string, availability_zone string, event_timestamp string, event struct< timestamp:string, flow_id:bigint, event_type:string, src_ip:string, src_port:int, dest_ip:string, dest_port:int, proto:string, app_proto:string, tls_inspected:boolean, netflow:struct< pkts:int, bytes:bigint, start:string, `end`:string, age:int, min_ttl:int, max_ttl:int, tcp_flags:struct< syn:boolean, fin:boolean, rst:boolean, psh:boolean, ack:boolean, urg:boolean > > > ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' LOCATION 's3://amzn-s3-demo-bucket/path_to_netflow_logs_folder/'; ``` 1. Modifique a cláusula `LOCATION` para especificar a pasta para seus logs no Amazon S3. 1. Execute a consulta `CREATE TABLE` no editor de consultas do Athena. Depois que a consulta for concluída, o Athena registrará a tabela `network_firewall_netflow_logs`, preparando os dados para os quais ela direciona para as consultas. ## Consulta de exemplo O exemplo de consulta de log do Netflow nesta seção filtra os eventos nos quais a inspeção TLS foi realizada. A consulta usa aliases para criar cabeçalhos de coluna de saída que mostram o `struct` ao qual a coluna pertence. Por exemplo, o título da coluna do campo `event.netflow.bytes` é `event_netflow_bytes` em vez de apenas`bytes`. Para personalizar ainda mais os nomes das colunas, você pode modificar os aliases de acordo com suas preferências. Por exemplo, você pode usar sublinhados ou outros separadores para delimitar os nomes de `struct` e os nomes dos campos. Lembre-se de modificar os nomes de colunas e as referências de `struct` com base na definição da tabela e nos campos que você deseja no resultado da consulta. ``` SELECT event.src_ip AS event_src_ip, event.dest_ip AS event_dest_ip, event.proto AS event_proto, event.app_proto AS event_app_proto, event.tls_inspected AS event_tls_inspected, event.netflow.pkts AS event_netflow_pkts, event.netflow.bytes AS event_netflow_bytes, event.netflow.tcp_flags.syn AS event_netflow_tcp_flags_syn FROM network_firewall_netflow_logs WHERE event.tls_inspected = true ``` # Consultar logs do Network Load Balancer Use o Athena para analisar e processar os logs do Network Load Balancer. Esses logs recebem informações detalhadas sobre as solicitações Transport Layer Security (TLS) enviadas ao Network Load Balancer. Você pode usar esses logs de acesso para analisar padrões de tráfego e solucionar problemas. Antes de analisar os logs de acesso do Network Load Balancer, habilite-os e configure-os para serem salvos no bucket de destino do Amazon S3. Para obter mais informações, além de informações sobre cada entrada de log de acesso do Network Load Balancer, consulte [Access logs for your Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-access-logs.html). **Para criar a tabela de logs do Network Load Balancer** 1. Copie e cole a instrução DDL a seguir no console do Athena. Verifique a [sintaxe ](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-access-logs.html#access-log-file-format) dos registros de log do Network Load Balancer. Atualize a instrução conforme necessário para incluir as colunas e o regex correspondentes aos seus registros de log. ``` CREATE EXTERNAL TABLE IF NOT EXISTS nlb_tls_logs ( type string, version string, time string, elb string, listener_id string, client_ip string, client_port int, target_ip string, target_port int, tcp_connection_time_ms double, tls_handshake_time_ms double, received_bytes bigint, sent_bytes bigint, incoming_tls_alert int, cert_arn string, certificate_serial string, tls_cipher_suite string, tls_protocol_version string, tls_named_group string, domain_name string, alpn_fe_protocol string, alpn_be_protocol string, alpn_client_preference_list string, tls_connection_creation_time string ) ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.RegexSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1', 'input.regex' = '([^ ]*) ([^ ]*) ([^ ]*) ([^ ]*) ([^ ]*) ([^ ]*):([0-9]*) ([^ ]*):([0-9]*) ([-.0-9]*) ([-.0-9]*) ([-0-9]*) ([-0-9]*) ([-0-9]*) ([^ ]*) ([^ ]*) ([^ ]*) ([^ ]*) ([^ ]*) ([^ ]*) ([^ ]*) ([^ ]*) ([^ ]*) ?([^ ]*)?( .*)?' ) LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/AWS_account_ID/elasticloadbalancing/region'; ``` 1. Modifique o bucket `LOCATION` do Amazon S3 para especificar o destino dos logs do Network Load Balancer. 1. Execute a consulta no console do Athena. Depois que a consulta for concluída, o Athena registrará a tabela `nlb_tls_logs`, preparando os dados dela para as consultas. ## Consultas de exemplo Para ver quantas vezes um certificado é usado, use uma consulta semelhante a este exemplo: ``` SELECT count(*) AS ct, cert_arn FROM "nlb_tls_logs" GROUP BY cert_arn; ``` A consulta a seguir mostra quantos usuários estão usando uma versão do TLS anterior à versão 1.3: ``` SELECT tls_protocol_version, COUNT(tls_protocol_version) AS num_connections, client_ip FROM "nlb_tls_logs" WHERE tls_protocol_version < 'tlsv13' GROUP BY tls_protocol_version, client_ip; ``` Use a consulta a seguir para identificar conexões que levam muito tempo de handshake do TLS. ``` SELECT * FROM "nlb_tls_logs" ORDER BY tls_handshake_time_ms DESC LIMIT 10; ``` Use a consulta a seguir para identificar e contar as versões de protocolo TLS e os conjuntos de cifras que foram negociados nos últimos 30 dias. ``` SELECT tls_cipher_suite, tls_protocol_version, COUNT(*) AS ct FROM "nlb_tls_logs" WHERE from_iso8601_timestamp(time) > current_timestamp - interval '30' day AND NOT tls_protocol_version = '-' GROUP BY tls_cipher_suite, tls_protocol_version ORDER BY ct DESC; ``` # Consultar logs de consultas do Amazon Route 53 Resolver Você pode criar tabelas do Athena para seus logs de consulta do Amazon Route 53 Resolver e consultá-las no Athena. O log de consulta do Route 53 Resolver é destinado ao registro de consultas de DNS feitas por recursos em uma VPC, recursos on-premises que usam endpoints do Resolver de entrada, consultas que usam um endpoint do Resolver de saída para resolução de DNS recursiva e consultas que usam regras de firewall de DNS do Route 53 Resolver para bloquear, permitir ou monitorar uma lista de domínios. Para obter mais informações sobre o log de consulta do Resolver, veja [Log de consulta do Resolver](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resolver-query-logs.html) no *Guia do desenvolvedor do Amazon Route 53*. Para obter informações sobre cada um dos campos nos logs, consulte [Valores que aparecem em logs de consultas do Resolver](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resolver-query-logs-format.html) no *Guia do desenvolvedor do Amazon Route 53*. **Topics** + [Criar a tabela de logs de consulta do resolvedor](querying-r53-resolver-logs-creating-the-table.md) + [Usar projeção de partições](querying-r53-resolver-logs-partitioning-example.md) + [Consultas de exemplo](querying-r53-resolver-logs-example-queries.md) # Criar a tabela de logs de consulta do resolvedor Você pode usar o editor de consultas no console do Athena para criar e consultar uma tabela com os logs de consulta do Route 53 Resolver. **Para criar e consultar uma tabela do Athena com os logs de consulta do Route 53 Resolver** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. No editor de consultas do Athena, insira a instrução `CREATE TABLE` a seguir. Substitua os valores da cláusula `LOCATION` pelos correspondentes ao local dos logs do Resolver no Amazon S3. ``` CREATE EXTERNAL TABLE r53_rlogs ( version string, account_id string, region string, vpc_id string, query_timestamp string, query_name string, query_type string, query_class string, rcode string, answers array< struct< Rdata: string, Type: string, Class: string> >, srcaddr string, srcport int, transport string, srcids struct< instance: string, resolver_endpoint: string >, firewall_rule_action string, firewall_rule_group_id string, firewall_domain_list_id string ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/aws_account_id/vpcdnsquerylogs/{vpc-id}/' ``` Como os dados de log de consulta do Resolver estão no formato JSON, a instrução CREATE TABLE usa a [Biblioteca SerDe do JSON](json-serde.md) para analisar os dados. **nota** O SerDe espera que cada documento JSON esteja em uma única linha de texto, sem caracteres de terminação de linha separando os campos no registro. Se o texto JSON estiver formatado para impressão, você poderá receber uma mensagem de erro como HIVE\$1CURSOR\$1ERROR: Row is not a valid JSON Object (HIVE\$1CURSOR\$1ERROR: a linha não é um objeto JSON válido) ou HIVE\$1CURSOR\$1ERROR: JsonParseException: Unexpected end-of-input: expected close marker for OBJECT (HIVE\$1CURSOR\$1ERROR: JSONParseException: Fim de entrada inesperado: marcador de fechamento esperado para OBJECT) quando tentar consultar a tabela após criá-la. Para obter mais informações, consulte [JSON Data Files](https://github.com/rcongiu/Hive-JSON-Serde#json-data-files) na documentação do OpenX SerDe no GitHub. 1. Selecione **Executar consulta**. A instrução cria uma tabela do Athena chamada `r53_rlogs` com colunas que representam cada um dos campos em seus dados de log do Resolver. 1. No editor de consultas do console do Athena, execute a consulta a seguir para verificar se a tabela foi criada. ``` SELECT * FROM "r53_rlogs" LIMIT 10 ``` # Usar projeção de partições O exemplo a seguir mostra uma declaração `CREATE TABLE` para logs de consulta do Resolver que usa projeção de partição e é particionada por VPC e por data. Para obter mais informações sobre projeção de partições, consulte [Usar projeção de partições com o Amazon Athena](partition-projection.md). ``` CREATE EXTERNAL TABLE r53_rlogs ( version string, account_id string, region string, vpc_id string, query_timestamp string, query_name string, query_type string, query_class string, rcode string, answers array< struct< Rdata: string, Type: string, Class: string> >, srcaddr string, srcport int, transport string, srcids struct< instance: string, resolver_endpoint: string >, firewall_rule_action string, firewall_rule_group_id string, firewall_domain_list_id string ) PARTITIONED BY ( `date` string, `vpc` string ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/route53-query-logging/AWSLogs/aws_account_id/vpcdnsquerylogs/' TBLPROPERTIES( 'projection.enabled' = 'true', 'projection.vpc.type' = 'enum', 'projection.vpc.values' = 'vpc-6446ae02', 'projection.date.type' = 'date', 'projection.date.range' = '2023/06/26,NOW', 'projection.date.format' = 'yyyy/MM/dd', 'projection.date.interval' = '1', 'projection.date.interval.unit' = 'DAYS', 'storage.location.template' = 's3://amzn-s3-demo-bucket/route53-query-logging/AWSLogs/aws_account_id/vpcdnsquerylogs/${vpc}/${date}/' ) ``` # Consultas de exemplo Os exemplos a seguir mostram algumas consultas do Athena que você pode executar em seus logs de consulta do Resolver. ## Exemplo 1: logs de consulta em ordem decrescente de query\$1timestamp A consulta a seguir exibe os resultados do log em ordem decrescente de `query_timestamp`. ``` SELECT * FROM "r53_rlogs" ORDER BY query_timestamp DESC ``` ## Exemplo 2: logs de consulta com horários de início e de término específicos As consultas a seguir analisam os logs entre meia-noite e 8h no dia 24 de setembro de 2020. Substitua os horários de início e de término de acordo com os seus requisitos. ``` SELECT query_timestamp, srcids.instance, srcaddr, srcport, query_name, rcode FROM "r53_rlogs" WHERE (parse_datetime(query_timestamp,'yyyy-MM-dd''T''HH:mm:ss''Z') BETWEEN parse_datetime('2020-09-24-00:00:00','yyyy-MM-dd-HH:mm:ss') AND parse_datetime('2020-09-24-00:08:00','yyyy-MM-dd-HH:mm:ss')) ORDER BY query_timestamp DESC ``` ## Exemplo 3: logs de consulta baseados em um padrão de nome especificado de consulta de DNS A consulta a seguir seleciona os registros com nome de consulta que inclui a string “example.com”. ``` SELECT query_timestamp, srcids.instance, srcaddr, srcport, query_name, rcode, answers FROM "r53_rlogs" WHERE query_name LIKE '%example.com%' ORDER BY query_timestamp DESC ``` ## Exemplo 4: solicitações de log de consulta sem resposta A consulta a seguir seleciona as entradas de log em que a solicitação não recebeu resposta. ``` SELECT query_timestamp, srcids.instance, srcaddr, srcport, query_name, rcode, answers FROM "r53_rlogs" WHERE cardinality(answers) = 0 ``` ## Exemplo 5: logs de consulta com uma resposta específica A consulta a seguir mostra os logs nos quais o valor `answer.Rdata` tem o endereço IP especificado. ``` SELECT query_timestamp, srcids.instance, srcaddr, srcport, query_name, rcode, answer.Rdata FROM "r53_rlogs" CROSS JOIN UNNEST(r53_rlogs.answers) as st(answer) WHERE answer.Rdata='203.0.113.16'; ``` # Consultar logs de eventos do Amazon SES É possível utilizar o Amazon Athena para consultar logs de eventos do [Amazon Simple Email Service](https://aws.amazon.com/ses/) (Amazon SES). O Amazon SES é uma plataforma de e-mail que oferece uma forma conveniente e com bom custo-benefício de enviar e receber e-mails usando seus próprios endereços de e-mail e domínios. Você pode monitorar suas atividades de envio do Amazon SES em nível granular usando eventos, métricas e estatísticas. Com base nas características que você define, é possível publicar eventos do Amazon SES no [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/), no [Amazon Data Firehose](https://aws.amazon.com/kinesis/data-firehose/) ou no [Amazon Simple Notification Service](https://aws.amazon.com/sns/). Depois que as informações forem armazenadas no Amazon S3, você poderá consultá-las no Amazon Athena. Para ver um exemplo de declaração `CREATE TABLE` do Athena para os logs do Amazon SES, incluindo etapas sobre como criar visualizações e nivelar arrays aninhadas nos dados do log de eventos do Amazon SES, consulte "Step 3: Using Amazon Athena to query the SES event logs" na postagem do blog da AWS, [Analyzing Amazon SES event data with AWS Analytics Services](https://aws.amazon.com/blogs/messaging-and-targeting/analyzing-amazon-ses-event-data-with-aws-analytics-services/). # Consultar os logs de fluxo do Amazon VPC Os logs de fluxo do Amazon Virtual Private Cloud capturam informações do tráfego de IP de entrada e saída das interfaces de rede em uma VPC. Use os logs para investigar padrões de tráfego de rede e identificar ameaças e riscos em toda a rede da VPC. Para consultar seus logs de fluxo da Amazon VPC, você tem duas opções: **** + **Console do Amazon VPC**: use o recurso de integração do Athena no console do Amazon VPC para gerar um modelo do CloudFormation que cria um banco de dados, um grupo de trabalho e uma tabela de logs de fluxo do Athena com particionamento para você. O modelo também cria um conjunto de [consultas de log de fluxo predefinidas](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs-athena.html#predefined-queries) que você pode usar para obter insights sobre o tráfego que passa pela VPC. Para obter mais informações sobre essa abordagem, consulte [Consultar logs de fluxo usando o Amazon Athena](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs-athena.html) no *Guia do usuário da Amazon VPC*. + **Console do Amazon Athena**: crie suas tabelas e consultas diretamente no console do Athena. Para obter mais informações, continue lendo esta página. Antes de começar a consultar os logs no Athena, [habilite os logs de fluxo da VPC](https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/flow-logs.html) e configure-os para serem salvos em seu bucket do Amazon S3. Depois de criar os logs, deixe-os em execução por alguns minutos para coletar alguns dados. Os logs são criados no formato de compactação GZIP que o Athena permite que você consulte diretamente. Ao criar um log de fluxo da VPC, você pode usar um formato personalizado quando desejar especificar os campos que devem ser retornados no log de fluxo e a ordem em que devem aparecer. Para obter mais informações sobre registros de logs de fluxo, consulte [Registros de log de fluxo](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html#flow-log-records) no *Guia do usuário da Amazon VPC*. ## Considerações e limitações Ao criar tabelas no Athena para logs de fluxo da Amazon VPC, lembre-se dos seguintes pontos: + Por padrão, no Athena, o Parquet acessará as colunas por nome. Para obter mais informações, consulte [Lidar com atualizações de esquemas](handling-schema-updates-chapter.md). + Use os nomes nos registros de log de fluxo para os nomes das colunas no Athena. Os nomes das colunas no esquema do Athena devem corresponder exatamente aos nomes dos campos nos logs de fluxo da Amazon VPC, com as seguintes diferenças: + Substitua os hifens nos nomes dos campos do log da Amazon VPC por sublinhados nos nomes das colunas do Athena. Para obter informações sobre caracteres aceitáveis em nomes de bancos de dados, nomes de tabelas e nomes de colunas no Athena, consulte [Nomear bancos de dados, tabelas e colunas](tables-databases-columns-names.md). + Escape os nomes de registro do log de fluxo que são [palavras-chave reservadas](reserved-words.md) no Athena, colocando-os entre caracteres de crase. + Os logs de fluxos da VPC são específicos da Conta da AWS. Quando você publica seus arquivos de log no Amazon S3, o caminho criado pela Amazon VPC no Amazon S3 inclui o ID da Conta da AWS que foi usada para criar o log de fluxo. Para obter mais informações, consulte [Publicar logs de fluxo no Amazon S3](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs-s3.html), no *Guia do usuário da Amazon VPC*. **Topics** + [Considerações e limitações](#vpc-flow-logs-common-considerations) + [Criar e consultar uma tabela para logs de fluxo da Amazon VPC](vpc-flow-logs-create-table-statement.md) + [Criar tabelas para logs de fluxo no formato Apache Parquet](vpc-flow-logs-parquet.md) + [Criar e consultar uma tabela para logs de fluxo da Amazon VPC com o uso de projeção de partições](vpc-flow-logs-partition-projection.md) + [Criar tabelas para logs de fluxo no formato do Apache Parquet com o uso de projeção de partições](vpc-flow-logs-partition-projection-parquet-example.md) + [Recursos adicionais](query-examples-vpc-logs-additional-resources.md) # Criar e consultar uma tabela para logs de fluxo da Amazon VPC O procedimento a seguir cria uma tabela da Amazon VPC para os logs de fluxo da Amazon VPC. Ao criar um log de fluxo em um formato personalizado, você cria uma tabela com campos que correspondem aos campos especificados quando criou o log de fluxo, na mesma ordem em que os especificou. **Para criar uma tabela do Athena para logs de fluxo da Amazon VPC** 1. Insira uma instrução DDL como a que se segue no editor de consultas do console do Athena, seguindo as diretrizes na seção [Considerações e limitações](vpc-flow-logs.md#vpc-flow-logs-common-considerations). A instrução do exemplo cria uma tabela com as colunas de logs de fluxo da Amazon VPC nas versões 2 a 5, conforme documentado em [Registros de log de fluxo](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html#flow-log-records). Se você usar outro conjunto ou outra ordem de colunas, modifique a instrução conforme apropriado. ``` CREATE EXTERNAL TABLE IF NOT EXISTS `vpc_flow_logs` ( version int, account_id string, interface_id string, srcaddr string, dstaddr string, srcport int, dstport int, protocol bigint, packets bigint, bytes bigint, start bigint, `end` bigint, action string, log_status string, vpc_id string, subnet_id string, instance_id string, tcp_flags int, type string, pkt_srcaddr string, pkt_dstaddr string, region string, az_id string, sublocation_type string, sublocation_id string, pkt_src_aws_service string, pkt_dst_aws_service string, flow_direction string, traffic_path int ) PARTITIONED BY (`date` date) ROW FORMAT DELIMITED FIELDS TERMINATED BY ' ' LOCATION 's3://amzn-s3-demo-bucket/prefix/AWSLogs/{account_id}/vpcflowlogs/{region_code}/' TBLPROPERTIES ("skip.header.line.count"="1"); ``` Observe os seguintes pontos: + A consulta especifica `ROW FORMAT DELIMITED` e omite a especificação de um SerDe. Isso significa que a consulta usa [Lazy Simple SerDe para arquivos CSV, TSV e com delimitação personalizada](lazy-simple-serde.md). Nesta consulta, os campos terminam com um espaço. + A cláusula `PARTITIONED BY` usa o tipo `date`. Isso torna possível usar operadores matemáticos em consultas para selecionar qual é mais antiga ou mais recente em relação a uma determinada data. **nota** Como `date` é uma palavra-chave reservada em instruções DDL, é necessário fazer o escape dela com acentos graves. Para obter mais informações, consulte [Escapar palavras-chave reservadas em consultas](reserved-words.md). + Para um log de fluxo da VPC com um formato personalizado diferente, modifique os campos para que correspondam aos campos especificados ao criar o log de fluxo. 1. Modifique `LOCATION 's3://amzn-s3-demo-bucket/prefix/AWSLogs/{account_id}/vpcflowlogs/{region_code}/'` para apontar para o bucket do Amazon S3 que contém os dados de log. 1. Execute a consulta no console do Athena. Depois que a consulta for concluída, o Athena registrará a tabela `vpc_flow_logs`, preparando os dados dela para você fazer as consultas. 1. Crie partições para poder ler os dados, conforme o exemplo de consulta a seguir. Esta consulta cria uma única partição para uma data especificada. Substitua os espaços reservados por data e local, conforme necessário. **nota** Esta consulta cria apenas uma única partição, para uma data especificada por você. Para automatizar o processo, use um script que execute essa consulta e crie partições dessa maneira para `year/month/day` ou use uma instrução `CREATE TABLE` que especifique a [projeção das partições](vpc-flow-logs-partition-projection.md). ``` ALTER TABLE vpc_flow_logs ADD PARTITION (`date`='YYYY-MM-dd') LOCATION 's3://amzn-s3-demo-bucket/prefix/AWSLogs/{account_id}/vpcflowlogs/{region_code}/YYYY/MM/dd'; ``` ## Exemplos de consulta para a tabela vpc\$1flow\$1logs Use o editor de consultas no console do Athena para executar instruções SQL na tabela criada. É possível salvar as consultas, visualizar consultas anteriores ou baixar os resultados da consulta no formato CSV. Nos exemplos a seguir, substitua `vpc_flow_logs` pelo nome da tabela. Modifique os valores das colunas e outras variáveis de acordo com os seus requisitos. A consulta de exemplo a seguir lista um máximo de 100 logs de fluxo para a data especificada. ``` SELECT * FROM vpc_flow_logs WHERE date = DATE('2020-05-04') LIMIT 100; ``` A consulta a seguir lista todas as conexões TCP rejeitadas e usa a coluna de partição de data recém-criada, `date`, para extrair dela o dia da semana em que ocorreram esses eventos. ``` SELECT day_of_week(date) AS day, date, interface_id, srcaddr, action, protocol FROM vpc_flow_logs WHERE action = 'REJECT' AND protocol = 6 LIMIT 100; ``` Para ver qual dos servidores está recebendo o maior número de solicitações HTTPS, use a consulta a seguir. Ela conta o número de pacotes recebidos na porta HTTPS 443, agrupa-os por endereço IP de destino e retorna os 10 principais da última semana. ``` SELECT SUM(packets) AS packetcount, dstaddr FROM vpc_flow_logs WHERE dstport = 443 AND date > current_date - interval '7' day GROUP BY dstaddr ORDER BY packetcount DESC LIMIT 10; ``` # Criar tabelas para logs de fluxo no formato Apache Parquet O procedimento a seguir cria uma tabela da Amazon VPC para os logs de fluxo da Amazon VPC no formato Apache Parquet. **Para criar uma tabela do Athena para logs de fluxo da Amazon VPC no formato Parquet** 1. Insira uma instrução DDL como a que se segue no editor de consultas do console do Athena, seguindo as diretrizes na seção [Considerações e limitações](vpc-flow-logs.md#vpc-flow-logs-common-considerations). A instrução do exemplo cria uma tabela com as colunas de logs de fluxo da Amazon VPC nas versões 2 a 5, conforme documentado em [Registros de log de fluxo](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html#flow-log-records) no formato Parquet, com partição do Hive por hora. Se você não tiver partições por hora, remova `hour` da cláusula `PARTITIONED BY`. ``` CREATE EXTERNAL TABLE IF NOT EXISTS vpc_flow_logs_parquet ( version int, account_id string, interface_id string, srcaddr string, dstaddr string, srcport int, dstport int, protocol bigint, packets bigint, bytes bigint, start bigint, `end` bigint, action string, log_status string, vpc_id string, subnet_id string, instance_id string, tcp_flags int, type string, pkt_srcaddr string, pkt_dstaddr string, region string, az_id string, sublocation_type string, sublocation_id string, pkt_src_aws_service string, pkt_dst_aws_service string, flow_direction string, traffic_path int ) PARTITIONED BY ( `aws-account-id` string, `aws-service` string, `aws-region` string, `year` string, `month` string, `day` string, `hour` string ) ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe' STORED AS INPUTFORMAT 'org.apache.hadoop.hive.ql.io.parquet.MapredParquetInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.parquet.MapredParquetOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/prefix/AWSLogs/' TBLPROPERTIES ( 'EXTERNAL'='true', 'skip.header.line.count'='1' ) ``` 1. Modifique a amostra `LOCATION 's3://amzn-s3-demo-bucket/prefix/AWSLogs/'` para apontar para o caminho do Amazon S3 que contém os dados de log. 1. Execute a consulta no console do Athena. 1. Se os dados estiverem em um formato compatível com o Hive, execute o comando a seguir no console do Athena para atualizar e carregar as partições do Hive no metastore. Após a conclusão da consulta, você pode consultar os dados na tabela `vpc_flow_logs_parquet`. ``` MSCK REPAIR TABLE vpc_flow_logs_parquet ``` Se não estiver usando dados compatíveis com o Hive, execute [ALTER TABLE ADD PARTITION](alter-table-add-partition.md) para carregar as partições. Para obter mais informações sobre como usar o Athena para consultar logs de fluxo da Amazon VPC no formato Parquet, consulte a publicação [Optimize performance and reduce costs for network analytics with VPC Flow Logs in Apache Parquet format](https://aws.amazon.com/blogs/big-data/optimize-performance-and-reduce-costs-for-network-analytics-with-vpc-flow-logs-in-apache-parquet-format/) (Otimize a performance e reduza os custos de análise de rede com logs de fluxo da VPC no formato Apache Parquet) no *blog sobre big data da AWS*. # Criar e consultar uma tabela para logs de fluxo da Amazon VPC com o uso de projeção de partições Use uma instrução `CREATE TABLE` como a que se segue para criar uma tabela, particionar a tabela e preencher as partições automaticamente usando [projeção de partições](partition-projection.md). Substitua o nome da tabela `test_table_vpclogs` no exemplo pelo nome da tabela. Edite a cláusula `LOCATION` para especificar o bucket do Amazon S3 que contém os dados de log da Amazon VPC. A instrução `CREATE TABLE` a seguir é para logs de fluxo da VPC fornecidos em um formato de particionamento em um estilo diferente do Hive. O exemplo permite a agregação de várias contas. Se você estiver centralizando logs de fluxo de VPC de diversas contas em um bucket do Amazon S3, o ID da conta deverá ser inserido no caminho do Amazon S3. ``` CREATE EXTERNAL TABLE IF NOT EXISTS test_table_vpclogs ( version int, account_id string, interface_id string, srcaddr string, dstaddr string, srcport int, dstport int, protocol bigint, packets bigint, bytes bigint, start bigint, `end` bigint, action string, log_status string, vpc_id string, subnet_id string, instance_id string, tcp_flags int, type string, pkt_srcaddr string, pkt_dstaddr string, az_id string, sublocation_type string, sublocation_id string, pkt_src_aws_service string, pkt_dst_aws_service string, flow_direction string, traffic_path int ) PARTITIONED BY (accid string, region string, day string) ROW FORMAT DELIMITED FIELDS TERMINATED BY ' ' LOCATION '$LOCATION_OF_LOGS' TBLPROPERTIES ( "skip.header.line.count"="1", "projection.enabled" = "true", "projection.accid.type" = "enum", "projection.accid.values" = "$ACCID_1,$ACCID_2", "projection.region.type" = "enum", "projection.region.values" = "$REGION_1,$REGION_2,$REGION_3", "projection.day.type" = "date", "projection.day.range" = "$START_RANGE,NOW", "projection.day.format" = "yyyy/MM/dd", "storage.location.template" = "s3://amzn-s3-demo-bucket/AWSLogs/${accid}/vpcflowlogs/${region}/${day}" ) ``` ## Exemplos de consulta para test\$1table\$1vpclogs Os exemplos de consulta a seguir consultam a `test_table_vpclogs` criada pela instrução `CREATE TABLE` anterior. Substitua `test_table_vpclogs` nas consultas pelo nome de sua própria tabela. Modifique os valores das colunas e outras variáveis de acordo com os seus requisitos. Para retornar as primeiras 100 entradas de log de acesso em ordem cronológica para o período de tempo especificado, execute uma consulta como a que se segue. ``` SELECT * FROM test_table_vpclogs WHERE day >= '2021/02/01' AND day < '2021/02/28' ORDER BY day ASC LIMIT 100 ``` Para ver qual servidor recebe os dez principais pacotes HTTP para um período de tempo especificado, execute uma consulta como a que se segue. A consulta conta o número de pacotes recebidos na porta HTTPS 443, agrupa-os por endereço IP de destino e retorna as 10 principais entradas da semana anterior. ``` SELECT SUM(packets) AS packetcount, dstaddr FROM test_table_vpclogs WHERE dstport = 443 AND day >= '2021/03/01' AND day < '2021/03/31' GROUP BY dstaddr ORDER BY packetcount DESC LIMIT 10 ``` Para retornar os logs que foram criados durante um período de tempo especificado, execute uma consulta como a que se segue. ``` SELECT interface_id, srcaddr, action, protocol, to_iso8601(from_unixtime(start)) AS start_time, to_iso8601(from_unixtime("end")) AS end_time FROM test_table_vpclogs WHERE DAY >= '2021/04/01' AND DAY < '2021/04/30' ``` Para retornar os logs de acesso de um endereço IP de origem em um determinado intervalo de tempo, execute uma consulta como a que se segue. ``` SELECT * FROM test_table_vpclogs WHERE srcaddr = '10.117.1.22' AND day >= '2021/02/01' AND day < '2021/02/28' ``` Para listas as conexões TCP rejeitadas, execute uma consulta como a que se segue. ``` SELECT day, interface_id, srcaddr, action, protocol FROM test_table_vpclogs WHERE action = 'REJECT' AND protocol = 6 AND day >= '2021/02/01' AND day < '2021/02/28' LIMIT 10 ``` Para retornar os logs de acesso para o intervalo de endereços IP que começa com `10.117`, execute uma consulta como a que se segue. ``` SELECT * FROM test_table_vpclogs WHERE split_part(srcaddr,'.', 1)='10' AND split_part(srcaddr,'.', 2) ='117' ``` Para retornar os logs de acesso para um endereço IP de destino em um determinado intervalo de tempo, execute uma consulta como a que segue. ``` SELECT * FROM test_table_vpclogs WHERE dstaddr = '10.0.1.14' AND day >= '2021/01/01' AND day < '2021/01/31' ``` # Criar tabelas para logs de fluxo no formato do Apache Parquet com o uso de projeção de partições A instrução `CREATE TABLE` de projeção de partições para logs de fluxo da VPC a seguir está no formato do Apache Parquet, não é compatível com o Hive e é particionada por hora e por data, em vez de por dia. Substitua o nome da tabela `test_table_vpclogs_parquet` no exemplo pelo nome da tabela. Edite a cláusula `LOCATION` para especificar o bucket do Amazon S3 que contém os dados de log da Amazon VPC. ``` CREATE EXTERNAL TABLE IF NOT EXISTS test_table_vpclogs_parquet ( version int, account_id string, interface_id string, srcaddr string, dstaddr string, srcport int, dstport int, protocol bigint, packets bigint, bytes bigint, start bigint, `end` bigint, action string, log_status string, vpc_id string, subnet_id string, instance_id string, tcp_flags int, type string, pkt_srcaddr string, pkt_dstaddr string, az_id string, sublocation_type string, sublocation_id string, pkt_src_aws_service string, pkt_dst_aws_service string, flow_direction string, traffic_path int ) PARTITIONED BY (region string, date string, hour string) ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe' STORED AS INPUTFORMAT 'org.apache.hadoop.hive.ql.io.parquet.MapredParquetInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.parquet.MapredParquetOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/prefix/AWSLogs/{account_id}/vpcflowlogs/' TBLPROPERTIES ( "EXTERNAL"="true", "skip.header.line.count" = "1", "projection.enabled" = "true", "projection.region.type" = "enum", "projection.region.values" = "us-east-1,us-west-2,ap-south-1,eu-west-1", "projection.date.type" = "date", "projection.date.range" = "2021/01/01,NOW", "projection.date.format" = "yyyy/MM/dd", "projection.hour.type" = "integer", "projection.hour.range" = "00,23", "projection.hour.digits" = "2", "storage.location.template" = "s3://amzn-s3-demo-bucket/prefix/AWSLogs/${account_id}/vpcflowlogs/${region}/${date}/${hour}" ) ``` # Recursos adicionais Para obter mais informações sobre como usar o Athena para analisar logs de fluxo de VPC, consulte as postagens do blog de AWS big data a seguir: + [Analyze VPC Flow Logs with point-and-click Amazon Athena integration](https://aws.amazon.com/blogs/networking-and-content-delivery/analyze-vpc-flow-logs-with-point-and-click-amazon-athena-integration/) (Análise de logs de fluxo de VPC com a integração de apontar e clicar do Amazon Athena) + [Como analisar logs de fluxo do VPC usando o Amazon Athena e o Quick](https://aws.amazon.com/blogs/big-data/analyzing-vpc-flow-logs-using-amazon-athena-and-amazon-quicksight/) + [Optimize performance and reduce costs for network analytics with VPC Flow Logs in Apache Parquet format](https://aws.amazon.com/blogs/big-data/optimize-performance-and-reduce-costs-for-network-analytics-with-vpc-flow-logs-in-apache-parquet-format/) (Otimização da performance e redução dos custos de análise de rede com os logs de fluxo de VPC no formato Apache Parquet) # Consultar logs do AWS WAF O AWS WAF é um firewall para aplicações Web que permite monitorar e controlar as solicitações HTTP e HTTPS que as aplicações Web protegidas recebem dos clientes. Você define como lidar com as solicitações da Web configurando regras dentro de uma lista de controle de acesso (ACL) da Web do AWS WAF. Depois, você protege uma aplicação Web associando a ela uma ACL da Web. Exemplos de recursos de aplicações Web que você pode proteger com o AWS WAF incluem distribuições do Amazon CloudFront, APIs REST do Amazon API Gateway e Application Load Balancers. Para obter mais informações sobre o AWS WAF, consulte [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) no *AWS WAF Developer Guide*. Os logs do AWS WAF incluem informações sobre o tráfego que é analisado pela sua ACL da Web, como a hora em que o AWS WAF recebeu a solicitação do recurso da AWS, os detalhes da solicitação e a ação para a regra correspondente de cada solicitação. Você pode configurar uma ACL da Web do AWS WAF para publicar logs em um de vários destinos, onde você pode consultá-los e visualizá-los. Para obter mais informações sobre a configuração de registro em log de ACL da Web e sobre o conteúdo dos logs do AWS WAF, consulte [Logging AWS WAF web ACL traffic](https://docs.aws.amazon.com/waf/latest/developerguide/logging.html) no *AWS WAF developer guide*. Para obter informações sobre como usar o Athena para analisar logs do AWS WAF para obter informações sobre a detecção de ameaças e possíveis ataques à segurança, consulte a postagem do blog Networking & Content Delivery da AWS [Como usar as consultas do Amazon Athena para analisar logs do AWS WAF e fornecer a visibilidade necessária para a detecção de ameaças](https://aws.amazon.com/blogs/networking-and-content-delivery/how-to-use-amazon-athena-queries-to-analyze-aws-waf-logs-and-provide-the-visibility-needed-for-threat-detection/). Para ver um exemplo de como agregar os logs do AWS WAF em um repositório central de data lake e consultá-los no Athena, leia a publicação em AWS Big Data Blog: [Analyzing AWS WAF logs with OpenSearch Service, Amazon Athena, and QuickSight](https://aws.amazon.com/blogs/big-data/analyzing-aws-waf-logs-with-amazon-es-amazon-athena-and-amazon-quicksight/). Este tópico fornece exemplos de instruções `CREATE TABLE` para projeção de partições, particionamento manual e uma que não usa nenhum particionamento. **nota** As instruções `CREATE TABLE` neste tópico podem ser usadas para logs do AWS WAF v1 e v2. Na v1, o campo `webaclid` contém um ID. Na v2, o campo `webaclid` contém um ARN completo. As instruções `CREATE TABLE` aqui tratam esse conteúdo de forma agnóstica usando o tipo de dados `string`. **Topics** + [Criar uma tabela para logs do S3 do AWS WAF no Athena usando a projeção de partições](create-waf-table-partition-projection.md) + [Criar uma tabela para logs do S3 do AWS WAF no Athena usando a partição manual](create-waf-table-manual-partition.md) + [Criar uma tabela para logs do AWS WAF sem particionamento](create-waf-table.md) + [Consultas de exemplo para logs do AWS WAF](query-examples-waf-logs.md) # Criar uma tabela para logs do S3 do AWS WAF no Athena usando a projeção de partições Como os logs do AWS WAF têm uma estrutura conhecida com um esquema de partição que você pode especificar antecipadamente, é possível reduzir o runtime das consultas e automatizar o gerenciamento de partições usando o recurso de [projeção de partições](partition-projection.md) do Athena. A projeção de partições adiciona automaticamente novas partições à medida que os dados são adicionados. Isso elimina a necessidade de adicionar manualmente as partições usando `ALTER TABLE ADD PARTITION`. A instrução de exemplo `CREATE TABLE` a seguir usa automaticamente a projeção de partições com base nos logs do AWS WAF desde uma data especificada até o dia de hoje para diferentes regiões da AWS. A cláusula `PARTITION BY` neste exemplo particiona por região e data, mas você pode modificá-la de acordo com seus requisitos. Modifique os campos conforme necessário para corresponder à saída do log. Nas cláusulas `LOCATION` e `storage.location.template`, substitua os espaços reservados *amzn-s3-demo-bucket* e *AWS\$1ACCOUNT\$1NUMBER* por valores que identifiquem o local do bucket do Amazon S3 dos seus logs do AWS WAF. Em ‭`projection.day.range`‬, substitua ‭*2021‭*/‭*01‭*‬/‭*01‭*‬ pela data de início que você desejar usar. Depois que você executar a consulta com êxito, poderá consultar a tabela. Você não precisa executar `ALTER TABLE ADD PARTITION` para carregar as partições. ``` CREATE EXTERNAL TABLE `waf_logs_partition_projection`( `timestamp` bigint, `formatversion` int, `webaclid` string, `terminatingruleid` string, `terminatingruletype` string, `action` string, `terminatingrulematchdetails` array>>, `httpsourcename` string, `httpsourceid` string, `rulegrouplist` array>>>,nonterminatingmatchingrules:array>>,challengeresponse:struct,captcharesponse:struct>>,excludedrules:string>>, `ratebasedrulelist` array>, `nonterminatingmatchingrules` array>>,challengeresponse:struct,captcharesponse:struct>>, `requestheadersinserted` array>, `responsecodesent` string, `httprequest` struct>,uri:string,args:string,httpversion:string,httpmethod:string,requestid:string,fragment:string,scheme:string,host:string>, `labels` array>, `captcharesponse` struct, `challengeresponse` struct, `ja3fingerprint` string, `ja4fingerprint` string, `oversizefields` string, `requestbodysize` int, `requestbodysizeinspectedbywaf` int) PARTITIONED BY ( `log_time` string) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/AWS_ACCOUNT_NUMBER/WAFLogs/cloudfront/testui/' TBLPROPERTIES ( 'projection.enabled'='true', 'projection.log_time.format'='yyyy/MM/dd/HH/mm', 'projection.log_time.interval'='1', 'projection.log_time.interval.unit'='minutes', 'projection.log_time.range'='2025/01/01/00/00,NOW', 'projection.log_time.type'='date', 'storage.location.template'='s3://amzn-s3-demo-bucket/AWSLogs/AWS_ACCOUNT_NUMBER/WAFLogs/cloudfront/testui/${log_time}') ``` **nota** O formato do caminho na cláusula `LOCATION` no exemplo corresponde ao padrão, mas pode variar com base na configuração AWS WAF implementada. Por exemplo, o exemplo de caminho de log do AWS WAF a seguir é para uma distribuição do CloudFront: ``` s3://amzn-s3-demo-bucket/AWSLogs/AWS_ACCOUNT_NUMBER/WAFLogs/cloudfront/cloudfronyt/2025/01/01/00/00/ ``` Se você tiver problemas ao criar ou consultar sua tabela de logs do AWS WAF, confirme a localização de seus dados de log ou [entre em contato com o Suporte](https://console.aws.amazon.com/support/home/). Para obter mais informações sobre projeção de partições, consulte [Usar projeção de partições com o Amazon Athena](partition-projection.md). # Criar uma tabela para logs do S3 do AWS WAF no Athena usando a partição manual Esta seção descreve como criar uma tabela para logs do AWS WAF usando a partição manual. Nas cláusulas `LOCATION` e `storage.location.template`, substitua os espaços reservados *amzn-s3-demo-bucket* e *AWS\$1ACCOUNT\$1NUMBER* por valores que identifiquem o local do bucket do Amazon S3 dos seus logs do AWS WAF. ``` CREATE EXTERNAL TABLE `waf_logs_manual_partition`( `timestamp` bigint, `formatversion` int, `webaclid` string, `terminatingruleid` string, `terminatingruletype` string, `action` string, `terminatingrulematchdetails` array>>, `httpsourcename` string, `httpsourceid` string, `rulegrouplist` array>>>,nonterminatingmatchingrules:array>>,challengeresponse:struct,captcharesponse:struct>>,excludedrules:string>>, `ratebasedrulelist` array>, `nonterminatingmatchingrules` array>>,challengeresponse:struct,captcharesponse:struct>>, `requestheadersinserted` array>, `responsecodesent` string, `httprequest` struct>,uri:string,args:string,httpversion:string,httpmethod:string,requestid:string,fragment:string,scheme:string,host:string>, `labels` array>, `captcharesponse` struct, `challengeresponse` struct, `ja3fingerprint` string, `ja4fingerprint` string, `oversizefields` string, `requestbodysize` int, `requestbodysizeinspectedbywaf` int) PARTITIONED BY ( `year` string, `month` string, `day` string, `hour` string, `min` string) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/AWSLogs/AWS_ACCOUNT_NUMBER/WAFLogs/cloudfront/webacl/' ``` # Criar uma tabela para logs do AWS WAF sem particionamento Esta seção descreve como criar uma tabela para logs do AWS WAF sem particionamento ou projeção de partição. **nota** Por motivos de desempenho e custo, não recomendamos usar o esquema não particionado para consultas. Para obter mais informações, consulte [Top 10 Performance Tuning Tips for Amazon Athena](https://aws.amazon.com/blogs/big-data/top-10-performance-tuning-tips-for-amazon-athena/) (As 10 melhores dicas para ajustar o desempenho do Amazon Athena) no AWS Big Data Blog. **Como criar a tabela de AWS WAF** 1. Copie e cole a instrução DDL a seguir no console do Athena. Modifique os campos conforme necessário para corresponder à saída do log. Modifique o valor de `LOCATION` do bucket do Amazon S3 de forma que ele corresponda a uma localização que armazena seus logs. Essa consulta usa o [OpenX JSON SerDe](openx-json-serde.md). **nota** O SerDe espera que cada documento JSON esteja em uma única linha de texto, sem caracteres de terminação de linha separando os campos no registro. Se o texto JSON estiver formatado para impressão, você poderá receber uma mensagem de erro como HIVE\$1CURSOR\$1ERROR: Row is not a valid JSON Object (HIVE\$1CURSOR\$1ERROR: a linha não é um objeto JSON válido) ou HIVE\$1CURSOR\$1ERROR: JsonParseException: Unexpected end-of-input: expected close marker for OBJECT (HIVE\$1CURSOR\$1ERROR: JSONParseException: Fim de entrada inesperado: marcador de fechamento esperado para OBJECT) quando tentar consultar a tabela após criá-la. Para obter mais informações, consulte [JSON Data Files](https://github.com/rcongiu/Hive-JSON-Serde#json-data-files) na documentação do OpenX SerDe no GitHub. ``` CREATE EXTERNAL TABLE `waf_logs`( `timestamp` bigint, `formatversion` int, `webaclid` string, `terminatingruleid` string, `terminatingruletype` string, `action` string, `terminatingrulematchdetails` array < struct < conditiontype: string, sensitivitylevel: string, location: string, matcheddata: array < string > > >, `httpsourcename` string, `httpsourceid` string, `rulegrouplist` array < struct < rulegroupid: string, terminatingrule: struct < ruleid: string, action: string, rulematchdetails: array < struct < conditiontype: string, sensitivitylevel: string, location: string, matcheddata: array < string > > > >, nonterminatingmatchingrules: array < struct < ruleid: string, action: string, overriddenaction: string, rulematchdetails: array < struct < conditiontype: string, sensitivitylevel: string, location: string, matcheddata: array < string > > >, challengeresponse: struct < responsecode: string, solvetimestamp: string >, captcharesponse: struct < responsecode: string, solvetimestamp: string > > >, excludedrules: string > >, `ratebasedrulelist` array < struct < ratebasedruleid: string, limitkey: string, maxrateallowed: int > >, `nonterminatingmatchingrules` array < struct < ruleid: string, action: string, rulematchdetails: array < struct < conditiontype: string, sensitivitylevel: string, location: string, matcheddata: array < string > > >, challengeresponse: struct < responsecode: string, solvetimestamp: string >, captcharesponse: struct < responsecode: string, solvetimestamp: string > > >, `requestheadersinserted` array < struct < name: string, value: string > >, `responsecodesent` string, `httprequest` struct < clientip: string, country: string, headers: array < struct < name: string, value: string > >, uri: string, args: string, httpversion: string, httpmethod: string, requestid: string >, `labels` array < struct < name: string > >, `captcharesponse` struct < responsecode: string, solvetimestamp: string, failureReason: string >, `challengeresponse` struct < responsecode: string, solvetimestamp: string, failureReason: string >, `ja3Fingerprint` string, `oversizefields` string, `requestbodysize` int, `requestbodysizeinspectedbywaf` int ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/prefix/' ``` 1. Execute a instrução `CREATE EXTERNAL TABLE` no editor de consultas do console do Athena. Isso registra a tabela `waf_logs` e disponibiliza os dados dela para consultas no Athena. # Consultas de exemplo para logs do AWS WAF Muitos dos exemplos de consultas nesta seção usam a tabela de projeção de partições criada anteriormente. Modifique o nome da tabela, os valores das colunas e outras variáveis de acordo com os seus requisitos. Para melhorar a performance das suas consultas e reduzir os custos, adicione a coluna de partição à condição de filtro. **Topics** + [Contar indicadores, endereços IP ou regras correspondentes](query-examples-waf-logs-count.md) + [Consultar usando data e hora](query-examples-waf-logs-date-time.md) + [Consultar solicitações ou endereços bloqueados](query-examples-waf-logs-blocked-requests.md) # Contar indicadores, endereços IP ou regras correspondentes Os exemplos nesta seção consultam contagens de itens de log de interesse. + [Count the number of referrers that contain a specified term](#waf-example-count-referrers-with-specified-term) + [Count all matched IP addresses in the last 10 days that have matched excluded rules](#waf-example-count-matched-ip-addresses) + [Group all counted managed rules by the number of times matched](#waf-example-group-managed-rules-by-times-matched) + [Group all counted custom rules by number of times matched](#waf-example-group-custom-rules-by-times-matched) **Example  – Contar o número de indicadores que contêm um termo especificado** A consulta a seguir conta o número de indicadores que contêm o termo “amazon” para o intervalo de datas especificado. ``` WITH test_dataset AS (SELECT header FROM waf_logs CROSS JOIN UNNEST(httprequest.headers) AS t(header) WHERE "date" >= '2021/03/01' AND "date" < '2021/03/31') SELECT COUNT(*) referer_count FROM test_dataset WHERE LOWER(header.name)='referer' AND header.value LIKE '%amazon%' ``` **Example  – Contar todos os endereços IP que corresponderam a regras excluídas nos últimos 10 dias** A consulta a seguir conta o número de vezes nos últimos 10 dias que o endereço IP correspondeu à regra excluída no grupo de regras. ``` WITH test_dataset AS (SELECT * FROM waf_logs CROSS JOIN UNNEST(rulegrouplist) AS t(allrulegroups)) SELECT COUNT(*) AS count, "httprequest"."clientip", "allrulegroups"."excludedrules", "allrulegroups"."ruleGroupId" FROM test_dataset WHERE allrulegroups.excludedrules IS NOT NULL AND from_unixtime(timestamp/1000) > now() - interval '10' day GROUP BY "httprequest"."clientip", "allrulegroups"."ruleGroupId", "allrulegroups"."excludedrules" ORDER BY count DESC ``` **Example  – Agrupar todas as regras gerenciadas contadas pelo número de vezes de correspondência** Se você definiu as ações de regras do grupo de regras como Count na configuração de ACL da Web antes de 27 de outubro de 2022, o AWS WAF salvou suas substituições no JSON da ACL da Web como `excludedRules`. Agora, a configuração JSON para substituir uma regra para Count está nas configurações `ruleActionOverrides`. Para obter mais informações, consulte [Substituições de ações em grupos de regras](https://docs.aws.amazon.com/waf/latest/developerguide/web-acl-rule-group-override-options.html) no *Guia do desenvolvedor do AWS WAF*. Para extrair regras gerenciadas no modo Count da nova estrutura de logs, consulte `nonTerminatingMatchingRules` na seção `ruleGroupList` em vez do campo `excludedRules`, como no exemplo a seguir. ``` SELECT count(*) AS count, httpsourceid, httprequest.clientip, t.rulegroupid, t.nonTerminatingMatchingRules FROM "waf_logs" CROSS JOIN UNNEST(rulegrouplist) AS t(t) WHERE action <> 'BLOCK' AND cardinality(t.nonTerminatingMatchingRules) > 0 GROUP BY t.nonTerminatingMatchingRules, action, httpsourceid, httprequest.clientip, t.rulegroupid ORDER BY "count" DESC Limit 50 ``` **Example  – Agrupar todas as regras personalizadas contadas pelo número de vezes de correspondência** A consulta a seguir agrupa todas as regras personalizadas contadas pelo número de vezes de correspondência. ``` SELECT count(*) AS count, httpsourceid, httprequest.clientip, t.ruleid, t.action FROM "waf_logs" CROSS JOIN UNNEST(nonterminatingmatchingrules) AS t(t) WHERE action <> 'BLOCK' AND cardinality(nonTerminatingMatchingRules) > 0 GROUP BY t.ruleid, t.action, httpsourceid, httprequest.clientip ORDER BY "count" DESC Limit 50 ``` Para obter informações sobre os locais de log de regras personalizadas e grupos de regras gerenciados, consulte [Monitoramento e ajuste](https://docs.aws.amazon.com/waf/latest/developerguide/web-acl-testing-activities.html) no *Guia do desenvolvedor do AWS WAF*. # Consultar usando data e hora Os exemplos desta seção incluem consultas que usam valores de data e hora. + [Return the timestamp field in human-readable ISO 8601 format](#waf-example-return-human-readable-timestamp) + [Return records from the last 24 hours](#waf-example-return-records-last-24-hours) + [Return records for a specified date range and IP address](#waf-example-return-records-date-range-and-ip) + [For a specified date range, count the number of IP addresses in five minute intervals](#waf-example-count-ip-addresses-in-date-range) + [Count the number of X-Forwarded-For IP in the last 10 days](#waf-example-count-x-forwarded-for-ip) **Example  – Retornar o campo de carimbo de data/hora no formato ISO 8601 legível** A consulta a seguir usa as funções `from_unixtime` e `to_iso8601` para retornar o campo `timestamp` no formato ISO 8601 legível (por exemplo, `2019-12-13T23:40:12.000Z` em vez de `1576280412771`). A consulta também retorna o nome, o ID e a solicitação da fonte HTTP. ``` SELECT to_iso8601(from_unixtime(timestamp / 1000)) as time_ISO_8601, httpsourcename, httpsourceid, httprequest FROM waf_logs LIMIT 10; ``` **Example  – Retornar os registros das últimas 24 horas** A consulta a seguir usa um filtro na cláusula `WHERE` para retornar o nome, o ID e os campos de solicitação da fonte HTTP dos registros nas últimas 24 horas. ``` SELECT to_iso8601(from_unixtime(timestamp/1000)) AS time_ISO_8601, httpsourcename, httpsourceid, httprequest FROM waf_logs WHERE from_unixtime(timestamp/1000) > now() - interval '1' day LIMIT 10; ``` **Example  – Retornar os registros para um intervalo de datas e endereço IP especificados** A consulta a seguir lista os registros em um intervalo de datas especificado para um endereço IP de cliente especificado. ``` SELECT * FROM waf_logs WHERE httprequest.clientip='53.21.198.66' AND "date" >= '2021/03/01' AND "date" < '2021/03/31' ``` **Example  – Para um intervalo de datas especificado, contar o número de endereços IP em intervalos de cinco minutos** A consulta a seguir conta, durante um determinado intervalo de datas, o número de endereços IP em intervalos de cinco minutos. ``` WITH test_dataset AS (SELECT format_datetime(from_unixtime((timestamp/1000) - ((minute(from_unixtime(timestamp / 1000))%5) * 60)),'yyyy-MM-dd HH:mm') AS five_minutes_ts, "httprequest"."clientip" FROM waf_logs WHERE "date" >= '2021/03/01' AND "date" < '2021/03/31') SELECT five_minutes_ts,"clientip",count(*) ip_count FROM test_dataset GROUP BY five_minutes_ts,"clientip" ``` **Example  – Contar o número de X-Forwarded-For IP nos últimos 10 dias** A consulta a seguir filtra os cabeçalhos de solicitação e conta o número de X-Forwarded-For IP nos últimos 10 dias. ``` WITH test_dataset AS (SELECT header FROM waf_logs CROSS JOIN UNNEST (httprequest.headers) AS t(header) WHERE from_unixtime("timestamp"/1000) > now() - interval '10' DAY) SELECT header.value AS ip, count(*) AS COUNT FROM test_dataset WHERE header.name='X-Forwarded-For' GROUP BY header.value ORDER BY COUNT DESC ``` Para obter mais informações sobre as funções de data e hora, consulte [Date and Time Functions and Operators](https://trino.io/docs/current/functions/datetime.html) (Funções e operadores de data e hora) na documentação do Trino. # Consultar solicitações ou endereços bloqueados Os exemplos desta seção consultam solicitações ou endereços bloqueados. + [Extract the top 100 IP addresses blocked by a specified rule type](#waf-example-extract-top-100-blocked-ip-by-rule) + [Count the number of times a request from a specified country has been blocked](#waf-example-count-request-blocks-from-country) + [Count the number of times a request has been blocked, grouping by specific attributes](#waf-example-count-request-blocks-by-attribute) + [Count the number of times a specific terminating rule ID has been matched](#waf-example-count-terminating-rule-id-matches) + [Retrieve the top 100 IP addresses blocked during a specified date range](#waf-example-top-100-ip-addresses-blocked-for-date-range) **Example  – Extrair os 100 primeiros endereços IP bloqueados por um tipo de regra especificado** A consulta a seguir extrai e conta os 100 primeiros endereços IP que foram bloqueados pela regra de encerramento `RATE_BASED` durante o intervalo de datas especificado. ``` SELECT COUNT(httpRequest.clientIp) as count, httpRequest.clientIp FROM waf_logs WHERE terminatingruletype='RATE_BASED' AND action='BLOCK' and "date" >= '2021/03/01' AND "date" < '2021/03/31' GROUP BY httpRequest.clientIp ORDER BY count DESC LIMIT 100 ``` **Example  – Contar o número de vezes que uma solicitação foi bloqueada de um país especificado** A consulta a seguir conta o número de vezes que a solicitação chegou de um endereço IP pertencente à Irlanda (IE) e foi bloqueada pela regra de encerramento `RATE_BASED`. ``` SELECT COUNT(httpRequest.country) as count, httpRequest.country FROM waf_logs WHERE terminatingruletype='RATE_BASED' AND httpRequest.country='IE' GROUP BY httpRequest.country ORDER BY count LIMIT 100; ``` **Example  – Contar o número de vezes que uma solicitação foi bloqueada, agrupando por atributos específicos** A consulta a seguir conta o número de vezes que a solicitação foi bloqueada, com resultados agrupados por WebACL, RuleId, ClientIP e HTTP Request URI. ``` SELECT COUNT(*) AS count, webaclid, terminatingruleid, httprequest.clientip, httprequest.uri FROM waf_logs WHERE action='BLOCK' GROUP BY webaclid, terminatingruleid, httprequest.clientip, httprequest.uri ORDER BY count DESC LIMIT 100; ``` **Example  – Contar o número de vezes em que houve correspondência com um ID de regra de encerramento específico** A consulta a seguir conta o número de vezes que um ID de regra de encerramento específico foi correspondido (`WHERE terminatingruleid='e9dd190d-7a43-4c06-bcea-409613d9506e'`). A consulta agrupa os resultados por WebACL, Action, ClientIP e HTTP Request URI. ``` SELECT COUNT(*) AS count, webaclid, action, httprequest.clientip, httprequest.uri FROM waf_logs WHERE terminatingruleid='e9dd190d-7a43-4c06-bcea-409613d9506e' GROUP BY webaclid, action, httprequest.clientip, httprequest.uri ORDER BY count DESC LIMIT 100; ``` **Example  – Recuperar os 100 primeiros endereços IP bloqueados durante um intervalo de datas especificado** A consulta a seguir extrai os 100 primeiros endereços IP que foram bloqueados durante um intervalo de datas especificado. A consulta também lista o número de vezes que os endereços IP foram bloqueados. ``` SELECT "httprequest"."clientip", "count"(*) "ipcount", "httprequest"."country" FROM waf_logs WHERE "action" = 'BLOCK' and "date" >= '2021/03/01' AND "date" < '2021/03/31' GROUP BY "httprequest"."clientip", "httprequest"."country" ORDER BY "ipcount" DESC limit 100 ``` Para obter informações sobre a consulta de logs do Amazon S3, veja os seguintes tópicos: + [Como analisar os logs de acesso do servidor do Amazon S3 usando o Athena?](https://aws.amazon.com/premiumsupport/knowledge-center/analyze-logs-athena/) na Central de Conhecimento da AWS + [Consultar os logs de acesso do Amazon S3 para solicitações usando o Amazon Athena](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-s3-access-logs-to-identify-requests.html#querying-s3-access-logs-for-requests) no Guia do usuário do Amazon Simple Storage Service + [Usar o AWS CloudTrail para identificar solicitações do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/cloudtrail-request-identification.html) no Guia do usuário do Amazon Simple Storage Service # Consultar logs do servidor Web armazenados no Amazon S3 Você pode usar o Athena para consultar logs do servidor Web armazenados no Amazon S3. Os tópicos desta seção mostram como criar tabelas no Athena para consultar logs do servidor Web em uma variedade de formatos. **Topics** + [Consulta de logs do Apache armazenados no Amazon S3](querying-apache-logs.md) + [Consultar logs do Internet Information Server (IIS) armazenados no Amazon S3](querying-iis-logs.md) # Consulta de logs do Apache armazenados no Amazon S3 Você pode usar o Amazon Athena para consultar [arquivos de log do servidor HTTP do Apache](https://httpd.apache.org/docs/2.4/logs.html) armazenados em sua conta do Amazon S3. Este tópico mostra como criar esquemas de tabela para consultar os arquivos de [log de acesso](https://httpd.apache.org/docs/2.4/logs.html#accesslog) do Apache no formato de log comum. Os campos no formato de log comum incluem endereço IP do cliente, ID do cliente, ID do usuário, carimbo de data/hora de recebimento da solicitação, texto da solicitação do cliente, código de status do servidor e tamanho do objeto retornado ao cliente. O exemplo de dados a seguir mostra o formato de log comum do Apache. ``` 198.51.100.7 - Li [10/Oct/2019:13:55:36 -0700] "GET /logo.gif HTTP/1.0" 200 232 198.51.100.14 - Jorge [24/Nov/2019:10:49:52 -0700] "GET /index.html HTTP/1.1" 200 2165 198.51.100.22 - Mateo [27/Dec/2019:11:38:12 -0700] "GET /about.html HTTP/1.1" 200 1287 198.51.100.9 - Nikki [11/Jan/2020:11:40:11 -0700] "GET /image.png HTTP/1.1" 404 230 198.51.100.2 - Ana [15/Feb/2019:10:12:22 -0700] "GET /favicon.ico HTTP/1.1" 404 30 198.51.100.13 - Saanvi [14/Mar/2019:11:40:33 -0700] "GET /intro.html HTTP/1.1" 200 1608 198.51.100.11 - Xiulan [22/Apr/2019:10:51:34 -0700] "GET /group/index.html HTTP/1.1" 200 1344 ``` ## Criar uma tabela no Athena para logs do Apache Antes de consultar os logs do Apache armazenados no Amazon S3, você deve criar um esquema de tabela para o Athena no qual ele possa ler os dados do log. Para criar uma tabela do Athena de logs do Apache, você pode usar [Grok SerDe](grok-serde.md). Para obter mais informações sobre como usar o SerDe do Grok, consulte [Escrever classificadores grok personalizados](https://docs.aws.amazon.com/glue/latest/dg/custom-classifier.html#custom-classifier-grok) no *Guia do desenvolvedor do AWS Glue*. **Para criar uma tabela no Athena para logs do servidor Web do Apache** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. Cole a instrução DDL a seguir no editor de consultas do Athena. Modifique os valores em `LOCATION 's3://amzn-s3-demo-bucket/apache-log-folder/'` para apontar para seus logs do Apache no Amazon S3. ``` CREATE EXTERNAL TABLE apache_logs ( client_ip string, client_id string, user_id string, request_received_time string, client_request string, server_status string, returned_obj_size string ) ROW FORMAT SERDE 'com.amazonaws.glue.serde.GrokSerDe' WITH SERDEPROPERTIES ( 'input.format'='^%{IPV4:client_ip} %{DATA:client_id} %{USERNAME:user_id} %{GREEDYDATA:request_received_time} %{QUOTEDSTRING:client_request} %{DATA:server_status} %{DATA: returned_obj_size}$' ) STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/apache-log-folder/'; ``` 1. Execute a consulta no console do Athena para registrar a tabela `apache_logs`. Quando a consulta for concluída, os logs estarão prontos para você consultar no Athena. ### Consultas de exemplo **Example – Filtro para erros 404** A consulta de exemplo a seguir seleciona a hora de recebimento da solicitação, o texto da solicitação do cliente e o código de status do servidor da tabela `apache_logs`. A cláusula `WHERE` filtra o código de status HTTP `404` (página não encontrada). ``` SELECT request_received_time, client_request, server_status FROM apache_logs WHERE server_status = '404' ``` A imagem a seguir mostra os resultados da consulta no editor de consultas do Athena. ![\[Consultar entradas HTTP 404 em um log do Apache pelo Athena.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-apache-logs-1.png) **Example – Filtro para solicitações com êxito** A consulta de exemplo a seguir seleciona o ID do usuário, a hora de recebimento da solicitação, o texto da solicitação do cliente e o código de status do servidor da tabela `apache_logs`. A cláusula `WHERE` filtra o código de status HTTP `200` (com êxito). ``` SELECT user_id, request_received_time, client_request, server_status FROM apache_logs WHERE server_status = '200' ``` A imagem a seguir mostra os resultados da consulta no editor de consultas do Athena. ![\[Consultar entradas HTTP 200 em um log do Apache pelo Athena.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-apache-logs-2.png) **Example – Filtrar por carimbo de data/hora** O exemplo a seguir consulta registros cujo horário de recebimento da solicitação é superior ao horário no carimbo de data/hora especificado. ``` SELECT * FROM apache_logs WHERE request_received_time > 10/Oct/2023:00:00:00 ``` # Consultar logs do Internet Information Server (IIS) armazenados no Amazon S3 Você pode usar o Amazon Athena para consultar os logs do servidor Web do Microsoft Internet Information Server (IIS) armazenados na sua conta do Amazon S3. O IIS usa uma [variedade](https://docs.microsoft.com/en-us/previous-versions/iis/6.0-sdk/ms525807(v%3Dvs.90)) de formatos de arquivo de log, mas este tópico mostra como criar esquemas de tabela para consultar logs no formato de arquivo de log do IIs e estendido do W3C usando o Athena. Como os formatos de arquivo de log do IIS e estendido do W3C usam delimitadores de caractere único (espaços e vírgulas, respectivamente) e não têm valores entre aspas, você pode usar o [LazySimpleSerDe](lazy-simple-serde.md) para criar tabelas do Athena para eles. **Topics** + [Consultar o formato de arquivo de log estendido do W3C](querying-iis-logs-w3c-extended-log-file-format.md) + [Consultar o formato de arquivo de log do IIS](querying-iis-logs-iis-log-file-format.md) + [Consulta ao formato de arquivo de log do NCSA](querying-iis-logs-ncsa-log-file-format.md) # Consultar o formato de arquivo de log estendido do W3C O formato de dados de arquivo de log [estendido do W3C](https://docs.microsoft.com/en-us/windows/win32/http/w3c-logging) tem campos separados por espaços. Os campos que aparecem nos logs estendidos do W3C são determinados por um administrador do servidor Web que escolhe quais campos de log serão incluídos. Os dados de log de exemplo a seguir têm os campos `date, time`, `c-ip`, `s-ip`, `cs-method`, `cs-uri-stem`, `sc-status`, `sc-bytes`, `cs-bytes`, `time-taken` e `cs-version`. ``` 2020-01-19 22:48:39 203.0.113.5 198.51.100.2 GET /default.html 200 540 524 157 HTTP/1.0 2020-01-19 22:49:40 203.0.113.10 198.51.100.12 GET /index.html 200 420 324 164 HTTP/1.0 2020-01-19 22:50:12 203.0.113.12 198.51.100.4 GET /image.gif 200 324 320 358 HTTP/1.0 2020-01-19 22:51:44 203.0.113.15 198.51.100.16 GET /faq.html 200 330 324 288 HTTP/1.0 ``` ## Criar uma tabela no Athena para logs estendidos do W3C Antes de consultar os logs estendidos do W3C, você deve criar um esquema de tabela para que o Athena possa ler os dados do log. **Para criar uma tabela no Athena para logs estendidos do W3C** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. Cole uma instrução DDL como a seguinte no console do Athena, observando estes pontos: 1. Adicione ou remova as colunas no exemplo para corresponder aos campos nos logs que você deseja consultar. 1. Os nomes de colunas no formato de arquivo de log estendido do W3C contêm hifens (`-`). No entanto, de acordo com as [Convenções de nomenclatura do Athena](tables-databases-columns-names.md), a instrução de exemplo `CREATE TABLE` os substitui por sublinhados (`_`). 1. Para especificar o delimitador de espaço, use `FIELDS TERMINATED BY ' '`. 1. Modifique os valores em `LOCATION 's3://amzn-s3-demo-bucket/w3c-log-folder/'` para apontar para seus logs estendidos do W3C no Amazon S3. ``` CREATE EXTERNAL TABLE `iis_w3c_logs`( date_col string, time_col string, c_ip string, s_ip string, cs_method string, cs_uri_stem string, sc_status string, sc_bytes string, cs_bytes string, time_taken string, cs_version string ) ROW FORMAT DELIMITED FIELDS TERMINATED BY ' ' STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/w3c-log-folder/' ``` 1. Execute a consulta no console do Athena para registrar a tabela `iis_w3c_logs`. Quando a consulta for concluída, os logs estarão prontos para você consultar no Athena. ## Exemplo de consulta select de log estendido do W3C A consulta de exemplo a seguir seleciona data, hora, destino da solicitação e tempo gasto na solicitação da tabela `iis_w3c_logs`. A cláusula `WHERE` filtra os casos em que o método HTTP é `GET` e o código de status HTTP é `200` (com êxito). ``` SELECT date_col, time_col, cs_uri_stem, time_taken FROM iis_w3c_logs WHERE cs_method = 'GET' AND sc_status = '200' ``` A imagem a seguir mostra os resultados da consulta no editor de consultas do Athena. ![\[Exemplo de resultados de consulta no Athena de arquivos de log estendidos do W3C armazenados no Amazon S3.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-iis-logs-1.png) ## Combinar os campos de data e hora Os campos `date` e `time` delimitados por espaços são entradas separadas nos dados de origem do log, mas você pode combiná-los em um carimbo de data/hora, se desejar. Use as funções [concat()](https://prestodb.io/docs/current/functions/string.html#concat) e [date\$1parse()](https://prestodb.io/docs/current/functions/datetime.html#date_parse) em uma consulta [SELECT](select.md) ou [CREATE TABLE AS SELECT](create-table-as.md) para concatenar e converter as colunas de data e hora no formato de carimbo de data/hora. O exemplo a seguir usa a consulta CTAS para criar uma nova tabela com uma coluna `derived_timestamp`. ``` CREATE TABLE iis_w3c_logs_w_timestamp AS SELECT date_parse(concat(date_col,' ', time_col),'%Y-%m-%d %H:%i:%s') as derived_timestamp, c_ip, s_ip, cs_method, cs_uri_stem, sc_status, sc_bytes, cs_bytes, time_taken, cs_version FROM iis_w3c_logs ``` Depois de criar a tabela, consulte a nova coluna de carimbo de data/hora diretamente, como no exemplo a seguir. ``` SELECT derived_timestamp, cs_uri_stem, time_taken FROM iis_w3c_logs_w_timestamp WHERE cs_method = 'GET' AND sc_status = '200' ``` A imagem a seguir mostra os resultados da consulta. ![\[Resultados da consulta de arquivo de log estendido do W3C em uma tabela com uma coluna de carimbo de data/hora derivada.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-iis-logs-1a.png) # Consultar o formato de arquivo de log do IIS Ao contrário do formato estendido do W3C, o [Formato de arquivo de log do IIS](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc728311(v%3dws.10)) tem um conjunto fixo de campos e inclui uma vírgula como delimitador. O LazySimpleSerDe trata a vírgula como o delimitador e o espaço após a vírgula como o início do próximo campo. O exemplo a seguir apresenta dados de amostra no formato de arquivo de log do IIS. ``` 203.0.113.15, -, 2020-02-24, 22:48:38, W3SVC2, SERVER5, 198.51.100.4, 254, 501, 488, 200, 0, GET, /index.htm, -, 203.0.113.4, -, 2020-02-24, 22:48:39, W3SVC2, SERVER6, 198.51.100.6, 147, 411, 388, 200, 0, GET, /about.html, -, 203.0.113.11, -, 2020-02-24, 22:48:40, W3SVC2, SERVER7, 198.51.100.18, 170, 531, 468, 200, 0, GET, /image.png, -, 203.0.113.8, -, 2020-02-24, 22:48:41, W3SVC2, SERVER8, 198.51.100.14, 125, 711, 868, 200, 0, GET, /intro.htm, -, ``` ## Criar uma tabela no Athena para arquivos de log do IIS Para consultar os logs no formato de arquivo de log do IIS no Amazon S3, crie primeiro um esquema de tabela para que o Athena possa ler os dados do log. **Para criar uma tabela no Athena para logs no formato de arquivo de log do IIS** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. Cole a seguinte instrução DDL no console do Athena, observando estes pontos: 1. Para especificar a vírgula como delimitador, use `FIELDS TERMINATED BY ','`. 1. Modifique os valores em LOCATION 's3://amzn-s3-demo-bucket/*iis-log-file-folder*/' para apontarem para seus arquivos de log no formato de log do IIS no Amazon S3. ``` CREATE EXTERNAL TABLE `iis_format_logs`( client_ip_address string, user_name string, request_date string, request_time string, service_and_instance string, server_name string, server_ip_address string, time_taken_millisec string, client_bytes_sent string, server_bytes_sent string, service_status_code string, windows_status_code string, request_type string, target_of_operation string, script_parameters string ) ROW FORMAT DELIMITED FIELDS TERMINATED BY ',' STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/iis-log-file-folder/' ``` 1. Execute a consulta no console do Athena para registrar a tabela `iis_format_logs`. Quando a consulta for concluída, os logs estarão prontos para você consultar no Athena. ## Exemplo de consulta select no formato de log do IIS A consulta de exemplo a seguir seleciona data, hora, destino da solicitação e tempo gasto em milissegundos da tabela `iis_format_logs`. A cláusula `WHERE` filtra os casos em que o tipo de solicitação é `GET` e o código de status HTTP é `200` (com êxito). Na consulta, observe que os espaços à esquerda em `' GET'` e `' 200'` são necessários para que a consulta seja bem-sucedida. ``` SELECT request_date, request_time, target_of_operation, time_taken_millisec FROM iis_format_logs WHERE request_type = ' GET' AND service_status_code = ' 200' ``` A imagem a seguir mostra os resultados da consulta dos dados de exemplo. ![\[Resultados da consulta de exemplo no Athena de arquivos de log no formato do IIS armazenados no Amazon S3.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-iis-logs-2.png) # Consulta ao formato de arquivo de log do NCSA O IIS também usa o formato de [log do NCSA](https://docs.microsoft.com/en-us/windows/win32/http/ncsa-logging), que tem um número fixo de campos em formato de texto ASCII separados por espaços. A estrutura é semelhante ao formato de log comum usado para logs de acesso do Apache. Os campos no formato de dados de log comum do NCSA incluem endereço IP do cliente, ID do cliente (não costuma ser usado), ID do usuário do domínio, carimbo de data/hora de recebimento da solicitação, texto da solicitação do cliente, código de status do servidor e tamanho do objeto retornado ao cliente. O exemplo a seguir mostra os dados no formato de log comum do NCSA, conforme documentado para o IIS. ``` 198.51.100.7 - ExampleCorp\Li [10/Oct/2019:13:55:36 -0700] "GET /logo.gif HTTP/1.0" 200 232 198.51.100.14 - AnyCompany\Jorge [24/Nov/2019:10:49:52 -0700] "GET /index.html HTTP/1.1" 200 2165 198.51.100.22 - ExampleCorp\Mateo [27/Dec/2019:11:38:12 -0700] "GET /about.html HTTP/1.1" 200 1287 198.51.100.9 - AnyCompany\Nikki [11/Jan/2020:11:40:11 -0700] "GET /image.png HTTP/1.1" 404 230 198.51.100.2 - ExampleCorp\Ana [15/Feb/2019:10:12:22 -0700] "GET /favicon.ico HTTP/1.1" 404 30 198.51.100.13 - AnyCompany\Saanvi [14/Mar/2019:11:40:33 -0700] "GET /intro.html HTTP/1.1" 200 1608 198.51.100.11 - ExampleCorp\Xiulan [22/Apr/2019:10:51:34 -0700] "GET /group/index.html HTTP/1.1" 200 1344 ``` ## Criar uma tabela no Athena para logs do NCSA do IIS Na instrução `CREATE TABLE`, você pode usar [Grok SerDe](grok-serde.md) e um padrão do grok similar ao usado nos [logs do servidor Web do Apache](querying-apache-logs.md). Ao contrário dos logs do Apache, o padrão do grok usa `%{DATA:user_id}` para o terceiro campo, em vez de `%{USERNAME:user_id}` para considerar a presença da barra invertida em `domain\user_id`. Para obter mais informações sobre como usar o SerDe do Grok, consulte [Escrever classificadores grok personalizados](https://docs.aws.amazon.com/glue/latest/dg/custom-classifier.html#custom-classifier-grok) no *Guia do desenvolvedor do AWS Glue*. **Para criar uma tabela no Athena para logs do servidor Web do NCSA do IIS** 1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home). 1. Cole a instrução DDL a seguir no editor de consultas do Athena. Modifique os valores em `LOCATION 's3://amzn-s3-demo-bucket/iis-ncsa-logs/'` para apontar para seus logs do NCSA do IIS no Amazon S3. ``` CREATE EXTERNAL TABLE iis_ncsa_logs( client_ip string, client_id string, user_id string, request_received_time string, client_request string, server_status string, returned_obj_size string ) ROW FORMAT SERDE 'com.amazonaws.glue.serde.GrokSerDe' WITH SERDEPROPERTIES ( 'input.format'='^%{IPV4:client_ip} %{DATA:client_id} %{DATA:user_id} %{GREEDYDATA:request_received_time} %{QUOTEDSTRING:client_request} %{DATA:server_status} %{DATA: returned_obj_size}$' ) STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/iis-ncsa-logs/'; ``` 1. Execute a consulta no console do Athena para registrar a tabela `iis_ncsa_logs`. Quando a consulta for concluída, os logs estarão prontos para você consultar no Athena. ## Exemplo de consultas Select para logs do NCSA do IIS **Example – Filtragem de erros 404** A consulta de exemplo a seguir seleciona a hora de recebimento da solicitação, o texto da solicitação do cliente e o código de status do servidor da tabela `iis_ncsa_logs`. A cláusula `WHERE` filtra o código de status HTTP `404` (página não encontrada). ``` SELECT request_received_time, client_request, server_status FROM iis_ncsa_logs WHERE server_status = '404' ``` A imagem a seguir mostra os resultados da consulta no editor de consultas do Athena. ![\[Consultar entradas HTTP 404 em um log do NCSA do IIS pelo Athena.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-iis-logs-3.png) **Example – Filtragem de solicitações com êxito de um domínio específico** A consulta de exemplo a seguir seleciona o ID do usuário, a hora de recebimento da solicitação, o texto da solicitação do cliente e o código de status do servidor da tabela `iis_ncsa_logs`. A cláusula `WHERE` filtra as solicitações com código de status HTTP `200`(com êxito) de usuários no domínio `AnyCompany`. ``` SELECT user_id, request_received_time, client_request, server_status FROM iis_ncsa_logs WHERE server_status = '200' AND user_id LIKE 'AnyCompany%' ``` A imagem a seguir mostra os resultados da consulta no editor de consultas do Athena. ![\[Consultar entradas HTTP 200 em um log do NCSA do IIS pelo Athena.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/querying-iis-logs-4.png)