# Usar o Apache Spark no Amazon Athena
<a name="notebooks-spark"></a>

O Amazon Athena facilita a execução interativa de data analytics e exploração de dados usando o Apache Spark, sem a necessidade de planejamento, configuração ou gerenciamento de recursos. Executar aplicações do Apache Spark no Athena significa enviar o código do Spark para processamento e receber os resultados diretamente sem a necessidade de uma configuração adicional. O Apache Spark no Amazon Athena corresponde a uma tecnologia sem servidor e oferece uma escalabilidade automática sob demanda que fornece computação instantânea para atender aos volumes de dados em constante mudança e aos requisitos de processamento.

Na versão de lançamento [Versão 3 do mecanismo PySpark](notebooks-spark-release-versions.md#notebooks-spark-release-versions-pyspark-3), você pode usar a experiência simplificada de cadernos no console do Amazon Athena para desenvolver aplicações do Apache Spark usando APIs de cadernos do Python ou do Athena.

Na versão de lançamento [Versão 3.5 do Apache Spark](notebooks-spark-release-versions.md#notebooks-spark-release-versions-spark-35), você pode executar o código Spark nos cadernos do Estúdio Unificado Amazon SageMaker ou em seus clientes Spark Connect compatíveis de preferência.

O Amazon Athena oferece os recursos a seguir:
+ **Uso do console**: envie suas aplicações do Spark usando o console do Amazon Athena (somente a versão 3 do mecanismo Pyspark).
+ **Criação de scripts**: crie e depure aplicações do Apache Spark de forma rápida e interativa em Python.
+ **Escalabilidade dinâmica**: o Amazon Athena determina automaticamente a memória e os recursos de computação necessários para executar um trabalho, além de escalar continuamente esses recursos de acordo com os máximos especificados. Essa escalabilidade dinâmica reduz os custos sem afetar a velocidade.
+ **Experiência de cadernos**: use os cadernos do Estúdio Unificado Amazon SageMaker AI para criar, editar e executar cálculos usando uma interface familiar. Na versão 3 do mecanismo Pyspark, você pode usar cadernos no console do Athena que sejam compatíveis com os cadernos Jupyter e que contenham uma lista de células que são executadas em ordem como cálculos. O conteúdo da célula pode incluir código, texto, Markdown, matemática, plotagens e mídia avançada.

Para obter informações adicionais, consulte [Run Spark SQL on Amazon Athena Spark](https://aws.amazon.com/blogs/big-data/run-spark-sql-on-amazon-athena-spark/) e [Explore your data lake using Amazon Athena for Apache Spark](https://aws.amazon.com/blogs/big-data/explore-your-data-lake-using-amazon-athena-for-apache-spark/) no *blog do AWS Big Data*. 

**Topics**
+ [Versões de liberação](notebooks-spark-release-versions.md)
+ [Considerações e limitações](notebooks-spark-considerations-and-limitations.md)
+ [Conceitos básicos](notebooks-spark-getting-started.md)
+ [Gerenciar arquivos de cadernos](notebooks-spark-managing.md)
+ [Editor de cadernos](notebooks-spark-editor.md)
+ [Usar formatos de tabela não Hive](notebooks-spark-table-formats.md)
+ [Suporte à biblioteca Python](notebooks-spark-python-library-support.md)
+ [Especificar uma configuração personalizada](notebooks-spark-custom-jar-cfg.md)
+ [Formatos de dados e de armazenamento compatíveis](notebooks-spark-data-and-storage-formats.md)
+ [Monitorar o Apache Spark](notebooks-spark-metrics.md)
+ [Atribuição de custos](notebooks-spark-cost-attribution.md)
+ [Registro em log e monitoramento](notebooks-spark-logging-monitoring.md)
+ [Acesso à interface do usuário do Spark](notebooks-spark-ui-access.md)
+ [Spark Connect](notebooks-spark-connect.md)
+ [Habilitar buckets de pagamento pelo solicitante](notebooks-spark-requester-pays.md)
+ [Integração do Lake Formation](notebooks-spark-lakeformation.md)
+ [Habilitar a criptografia do Spark](notebooks-spark-encryption.md)
+ [Acesso ao catálogo entre contas](spark-notebooks-cross-account-glue.md)
+ [Cotas de serviço](notebooks-spark-quotas.md)
+ [APIs do Athena Spark](notebooks-spark-api-list.md)
+ [Solução de problemas](notebooks-spark-troubleshooting.md)

# Versões de liberação
<a name="notebooks-spark-release-versions"></a>

O Amazon Athena para Apache Spark oferece as seguintes versões de lançamento:

## Versão 3 do mecanismo PySpark
<a name="notebooks-spark-release-versions-pyspark-3"></a>

A versão 3 do PySpark inclui a versão 3.2.1 do Apache Spark. Com essa versão, você pode executar o código Spark em cadernos no console do Athena.

## Versão 3.5 do Apache Spark
<a name="notebooks-spark-release-versions-spark-35"></a>

A versão 3.5 do Apache Spark é baseada no Amazon EMR 7.12 e inclui a versão 3.5.6 do Apache Spark. Com essa versão, você pode executar o código Spark no caderno do Estúdio Unificado Amazon SageMaker AI ou em seus clientes Spark compatíveis de preferência. Essa versão inclui os principais recursos para oferecer uma experiência aprimorada para workloads interativas:
+ **Secure Spark Connect**: inclui o Spark Connect como um endpoint da AWS autenticado e autorizado.
+ **Atribuição de custos no nível de sessão**: os usuários podem acompanhar os custos por sessão interativa nos relatórios de Custos e Uso e do Explorador de Custos da AWS. Para obter mais informações, consulte [Atribuição de custos no nível de sessão](notebooks-spark-cost-attribution.md).
+ **Recursos avançados de depuração**: inclui suporte em tempo real à interface do usuário e ao servidor de histórico do Spark para depurar workloads tanto das APIs quanto dos cadernos. Para obter mais informações, consulte [Acesso à interface do usuário do Spark](notebooks-spark-ui-access.md#notebooks-spark-ui-access-methods).
+ **Suporte a acesso sem filtros**: acesse tabelas protegidas do Catálogo de Dados do AWS Glue em que você tem permissões completas de tabela. Para obter mais informações, consulte [Uso do Lake Formation com grupos de trabalho do Athena Spark](notebooks-spark-lakeformation.md).

### Propriedades padrão do Spark
<a name="notebooks-spark-release-versions-spark-35-default-properties"></a>

A tabela a seguir lista as propriedades do Spark e seus valores padrão que são aplicados às sessões do Athena SparkConnect.


| Chave | Valor padrão | Descrição | 
| --- | --- | --- | 
|  `spark.app.id`  |  `<Athena SessionId>`  |  Não é modificável.  | 
|  `spark.app.name`  |  `default`  |    | 
|  `spark.driver.cores`  |  `4`  |  O número de núcleos que o driver usa. Não é modificável durante a execução inicial.  | 
|  `spark.driver.memory`  |  `10g`  |  A quantidade de memória que cada driver usa. Não é modificável durante a execução inicial.  | 
|  `spark.driver.memoryOverhead`  |  `6g`  |  Quantidade de sobrecarga de memória atribuída às workloads do Python e a outros processos em execução no driver. Não é modificável durante a execução inicial.  | 
|  `spark.cortex.driver.disk`  |  `64g`  |  O disco do driver do Spark. Não é modificável durante a execução inicial.  | 
|  `spark.executor.cores`  |  `4`  |  O número de núcleos que cada executor usa. Não é modificável durante a execução inicial.  | 
|  `spark.executor.memory`  |  `10g`  |  A quantidade de memória que cada driver usa.  | 
|  `spark.executor.memoryOverhead`  |  `6g`  |  Quantidade de sobrecarga de memória atribuída às workloads do Python e a outros processos em execução no executor. Não é modificável durante a execução inicial.  | 
|  `spark.cortex.executor.disk`  |  `64g`  |  O disco do executor do Spark. Não é modificável durante a execução inicial.  | 
|  `spark.cortex.executor.architecture`  |  `AARCH_64`  |  Arquitetura do executor.  | 
|  `spark.driver.extraJavaOptions`  |  `-Djava.net.preferIPv6Addresses=false -XX:+IgnoreUnrecognizedVMOptions --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.base/jdk.internal.ref=ALL-UNNAMED --add-opens=java.base/sun.nio.ch=ALL-UNNAMED --add-opens=java.base/sun.nio.cs=ALL-UNNAMED --add-opens=java.base/sun.security.action=ALL-UNNAMED --add-opens=java.base/sun.util.calendar=ALL-UNNAMED --add-opens=java.security.jgss/sun.security.krb5=ALL-UNNAMED -Djdk.reflect.useDirectMethodHandle=false`  |  Opções extras de Java para o driver do Spark. Não é modificável durante a execução inicial.  | 
|  `spark.executor.extraJavaOptions`  |  `-Djava.net.preferIPv6Addresses=false -XX:+IgnoreUnrecognizedVMOptions --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.base/jdk.internal.ref=ALL-UNNAMED --add-opens=java.base/sun.nio.ch=ALL-UNNAMED --add-opens=java.base/sun.nio.cs=ALL-UNNAMED --add-opens=java.base/sun.security.action=ALL-UNNAMED --add-opens=java.base/sun.util.calendar=ALL-UNNAMED --add-opens=java.security.jgss/sun.security.krb5=ALL-UNNAMED -Djdk.reflect.useDirectMethodHandle=false`  |  Opções extras de Java para o executor do Spark. Não é modificável durante a execução inicial.  | 
|  `spark.executor.instances`  |  `1`  |  O número de contêineres do executor do Spark a serem alocados.  | 
|  `spark.dynamicAllocation.enabled`  |  `TRUE`  |  Opção que ativa a alocação dinâmica de recursos. Essa opção aumenta ou reduz a escala verticalmente do número de executores registrados na aplicação com base na workload.  | 
|  `spark.dynamicAllocation.minExecutors`  |  `0`  |  O limite inferior do número de executores se você ativar a alocação dinâmica.  | 
|  `spark.dynamicAllocation.maxExecutors`  |  `59`  |  O limite superior do número de executores se você ativar a alocação dinâmica.  | 
|  `spark.dynamicAllocation.initialExecutors`  |  `1`  |  O número inicial de executores a serem executados se você ativar a alocação dinâmica.  | 
|  `spark.dynamicAllocation.executorIdleTimeout`  |  `60s`  |  O tempo que um executor pode permanecer inativo antes que o Spark o remova. Isso só se aplica se você ativar a alocação dinâmica.  | 
|  `spark.dynamicAllocation.shuffleTracking.enabled`  |  `TRUE`  |  O DRA habilitado exige que o rastreamento de shuffle esteja habilitado.  | 
|  `spark.dynamicAllocation.sustainedSchedulerBacklogTimeout`  |  `1s`  |  O tempo limite define por quanto tempo o programador do Spark deve observar um backlog persistente de tarefas pendentes antes de acionar uma solicitação ao gerenciador de clusters para iniciar novos executores.  | 
|  `spark.sql.catalogImplementation`  |  `hive`  |    | 
|  `spark.hadoop.hive.metastore.client.factory.class`  |  `com.amazonaws.glue.catalog.metastore.AWSGlueDataCatalogHiveClientFactory`  |  A classe de implementação do metastore do AWS Glue.  | 
|  `spark.hadoop.hive.metastore.glue.catalogid`  |  `<accountId>`  |  AccountId do catálogo do AWS Glue.  | 
|  `spark.sql.hive.metastore.sharedPrefixes`  |  `software.amazon.awssdk.services.dynamodb`  |  A propriedade especifica uma lista separada por vírgulas de prefixos de pacotes das classes que devem ser carregadas pelo Application ClassLoader em vez do ClassLoader isolado criado para o código do Hive Metastore Client.  | 
|  `spark.hadoop.fs.s3.impl`  |  `org.apache.hadoop.fs.s3a.S3AFileSystem`  |  Define a implementação do cliente S3 para usar o S3A.  | 
|  `spark.hadoop.fs.s3a.impl`  |  `org.apache.hadoop.fs.s3a.S3AFileSystem`  |  Define a implementação do cliente S3A (S3A).  | 
|  `spark.hadoop.fs.s3n.impl`  |  `org.apache.hadoop.fs.s3a.S3AFileSystem`  |  Define a implementação do cliente Native S3 (S3N) para usar o S3A.  | 
|  `spark.hadoop.fs.AbstractFileSystem.s3.impl`  |  `org.apache.hadoop.fs.s3a.S3A`  |    | 
|  `spark.hadoop.fs.s3a.aws.credentials.provider`  |  `software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider`  |    | 
|  `spark.hadoop.fs.s3.customAWSCredentialsProvider`  |  `com.amazonaws.auth.DefaultAWSCredentialsProviderChain`  |    | 
|  `spark.hadoop.mapreduce.output.fs.optimized.committer.enabled`  |  `TRUE`  |  Essa propriedade habilita um protocolo de confirmação otimizado para trabalhos do Spark ao gravar dados no Amazon S3. Quando definido como true, ajuda o Spark a evitar operações onerosas de renomeação de arquivos, resultando em gravações atômicas mais rápidas e confiáveis em comparação com o confirmador padrão do Hadoop.  | 
|  `spark.hadoop.fs.s3a.endpoint.region`  |  `<REGION>`  |  Esta configuração define explicitamente a região da AWS para o bucket do Amazon S3 acessado por meio do cliente S3A.  | 
|  `spark.hadoop.fs.s3.getObject.initialSocketTimeoutMilliseconds`  |  `2000`  |  Especifica o tempo limite de conexão do soquete em milissegundos.  | 
|  `spark.hadoop.fs.s3a.committer.magic.enabled`  |  `TRUE`  |  Habilita o S3A “Magic” Committer, um protocolo de confirmação específico, mas de alta performance, que depende do suporte do gerenciador de clusters subjacente para caminhos especiais.  | 
|  `spark.hadoop.fs.s3a.committer.magic.track.commits.in.memory.enabled`  |  `TRUE`  |  Relevante somente quando o Magic Committer está habilitado, especifica se a lista de arquivos confirmados por uma tarefa deve ser rastreada na memória em vez de ser gravada em arquivos temporários de disco.  | 
|  `spark.hadoop.fs.s3a.committer.name`  |  `magicv2`  |  Esta configuração seleciona explicitamente o algoritmo específico do S3A Output Committer a ser usado (por exemplo, directory, partitioned ou magic). Ao especificar o nome, você escolhe a estratégia que gerencia dados temporários, lida com falhas de tarefas e executa a confirmação atômica final no caminho de destino do Amazon S3.  | 
|  `spark.hadoop.fs.s3.s3AccessGrants.enabled`  |  `FALSE`  |  A propriedade permite o suporte à Concessão de Acesso do Amazon S3 ao acessar dados do Amazon S3 por meio do cliente do sistema de arquivos S3A/EMRFS.  | 
|  `spark.hadoop.fs.s3.s3AccessGrants.fallbackToIAM`  |  `FALSE`  |  Quando a Concessão de Acesso do Amazon S3 está habilitada, essa propriedade controla se o cliente do Amazon S3 deverá recorrer às credenciais tradicionais do IAM se a pesquisa da Concessão de Acesso falhar ou não fornecer permissões suficientes.  | 
|  `spark.pyspark.driver.python`  |  `/usr/bin/python3.11`  |  Caminho do Python para o driver.  | 
|  `spark.pyspark.python`  |  `/usr/bin/python3.11`  |  Caminho do Python para o executor.  | 
|  `spark.python.use.daemon`  |  `TRUE`  |  Essa configuração controla se o Spark utiliza um processo daemon de operador do Python em cada executor. Quando habilitado (true, o padrão), o executor mantém o operador do Python ativo entre as tarefas para evitar a sobrecarga de iniciar e inicializar repetidamente um novo interpretador do Python para cada tarefa, melhorando de forma significativa a performance das aplicações do PySpark.  | 
|  `spark.sql.execution.arrow.pyspark.enabled`  |  `TRUE`  |  Permite o uso do Apache Arrow para otimizar a transferência de dados entre os processos da JVM e do Python no PySpark.  | 
|  `spark.sql.execution.arrow.pyspark.fallback.enabled`  |  `TRUE`  |  Propriedade de configuração que controla o comportamento do Spark quando ocorre um erro durante a transferência de dados entre a JVM e o Python usando a otimização do Apache Arrow.  | 
|  `spark.sql.parquet.fs.optimized.committer.optimization-enabled`  |  `TRUE`  |  Propriedade de configuração que controla se o Spark usa um confirmador de arquivos otimizado ao gravar arquivos Parquet em determinados sistemas de arquivos, especificamente sistemas de armazenamento em nuvem, como o Amazon S3.  | 
|  `spark.sql.parquet.output.committer.class`  |  `com.amazon.emr.committer.EmrOptimizedSparkSqlParquetOutputCommitter`  |  Propriedade de configuração do Spark que especifica o nome de classe totalmente qualificado do Hadoop OutputCommitter a ser usado ao gravar arquivos Parquet.  | 
|  `spark.resourceManager.cleanupExpiredHost`  |  `TRUE`  |  Essa propriedade controla se o Driver limpa ativamente os recursos da aplicação do Spark associados aos executores que estavam sendo executados em nós que foram excluídos ou expiraram.  | 
|  `spark.blacklist.decommissioning.enabled`  |  `TRUE`  |  A propriedade permite que a lógica do Spark coloque automaticamente na lista de restrições os executores que estão atualmente sendo desativados (desligamento normal) pelo gerenciador de clusters. Isso impede que o programador envie novas tarefas aos executores que estão prestes a sair, melhorando a estabilidade do trabalho ao reduzir a escala verticalmente dos recursos.  | 
|  `spark.blacklist.decommissioning.timeout`  |  `1h`  |  Tempo máximo que o Spark aguardará até que uma tarefa seja migrada com êxito de um executor em desativação antes de colocar o host na lista de restrições.  | 
|  `spark.stage.attempt.ignoreOnDecommissionFetchFailure`  |  `TRUE`  |  Informa ao Spark para que seja leniente e não invalide uma tentativa de etapa por completo se ocorrer uma falha de busca ao ler dados de shuffle de um executor em desativação. A falha de busca é considerada recuperável, e o Spark buscará novamente os dados em um local diferente (possivelmente exigindo reprocessamento), priorizando a conclusão do trabalho em vez do tratamento rigoroso de erros durante desligamentos regulares.  | 
|  `spark.decommissioning.timeout.threshold`  |  `20`  |  Essa propriedade geralmente é usada internamente ou em configurações específicas do gerenciador de clusters para definir a duração total máxima que o Spark espera que o processo de desativação do host leve. Se o tempo real de desativação exceder esse limite, o Spark poderá tomar medidas agressivas, como colocar o host na lista de restrições ou solicitar o encerramento forçado para liberar o recurso.  | 
|  `spark.files.fetchFailure.unRegisterOutputOnHost`  |  `TRUE`  |  Quando uma tarefa falha ao obter dados de shuffle ou de RDD de um host específico, definir o valor como true instrui o Spark a cancelar o registro de todos os blocos de saída associados à aplicação com falha nesse host. Isso evita que futuras tarefas tentem buscar dados de um host não confiável, forçando o Spark a recalcular os blocos necessários em outros lugares e aumentando a robustez do trabalho contra problemas intermitentes de rede.  | 

# Considerações e limitações
<a name="notebooks-spark-considerations-and-limitations"></a>

## Versão 3.5 do Apache Spark
<a name="notebooks-spark-considerations-spark-35"></a>

Confira a seguir as considerações e limitações da versão de lançamento do Apache Spark versão 3.5:
+ Essa versão de lançamento está disponível nas seguintes Regiões da AWS:
  + Ásia-Pacífico (Mumbai)
  + Ásia-Pacífico (Seul)
  + Ásia-Pacífico (Singapura)
  + Ásia-Pacífico (Sydney)
  + Ásia-Pacífico (Tóquio)
  + Canadá (Central)
  + Europa (Frankfurt)
  + Europa (Irlanda)
  + Europa (Londres)
  + Europa (Paris)
  + Europa (Estocolmo)
  + América do Sul (São Paulo)
  + Leste dos EUA (Norte da Virgínia)
  + Leste dos EUA (Ohio)
  + Oeste dos EUA (Oregon)
+ Essa versão do mecanismo não é compatível com cadernos no console do Athena ou APIs de cadernos. Em vez disso, essa versão vem integrada aos cadernos do Estúdio Unificado Amazon SageMaker AI. Você também pode usar clientes Spark Connect compatíveis.
+ As APIs de cálculo: `StartCalculationExecution`, `ListCalculationExecutions` e `GetCalculationExecution` não são compatíveis com esta versão.
+ Você não pode atualizar um grupo de trabalho da versão 3 do mecanismo PySpark para a versão 3.5 do Apache Spark.

## Versão 3 do mecanismo Pyspark
<a name="notebooks-spark-considerations-pyspark-3"></a>

Confira abaixo as considerações e limitações da versão de lançamento do mecanismo Pyspark versão 3:
+ Essa versão de lançamento está disponível nas seguintes Regiões da AWS:
  + Ásia-Pacífico (Mumbai)
  + Ásia-Pacífico (Singapura)
  + Ásia-Pacífico (Sydney)
  + Ásia-Pacífico (Tóquio)
  + Europa (Frankfurt)
  + Europa (Irlanda)
  + Leste dos EUA (N. da Virgínia)
  + Leste dos EUA (Ohio)
  + Oeste dos EUA (Oregon)
+ AWS Lake FormationNão há suporte ao .
+ Tabelas que usam projeção de partição não são compatíveis.
+ Grupos de trabalho habilitados para o Apache Spark podem usar o editor de cadernos do Athena, mas não o editor de consultas do Athena. Somente os grupos de trabalho do Athena podem usar o editor de consultas do Athena.
+ Não há suporte para consultas de visualização entre mecanismos. As visualizações criadas pelo SQL do Athena não podem ser consultadas pelo Athena para Spark. Como as visualizações dos dois mecanismos são implementadas de maneira diferente, elas não são compatíveis para uso entre mecanismos.
+ Não há compatibilidade com MLLib (biblioteca de machine learning do Apache Spark) e com o pacote `pyspark.ml`. Para obter uma lista de bibliotecas Python compatíveis, consulte a [Lista de bibliotecas Python pré-instaladas](notebooks-spark-preinstalled-python-libraries.md).
+ No momento, `pip install` não é compatível com as sessões do Athena para Spark. 
+ Somente uma sessão ativa por caderno é permitida. 
+ Quando vários usuários usam o console para abrir uma sessão existente em um grupo de trabalho, eles acessam o mesmo caderno. Para evitar confusão, abra apenas sessões criadas por você mesmo.
+ Os domínios de hospedagem para aplicações do Apache Spark que você pode usar com o Amazon Athena (por exemplo, `analytics-gateway.us-east-1.amazonaws.com`) estão registrados na Lista [Public Suffix List (PSL)](https://publicsuffix.org/list/public_suffix_list.dat) da Internet. Se você precisar definir cookies confidenciais em seus domínios, recomendamos que use cookies com um prefixo `__Host-` para ajudar a defender o domínio contra tentativas de falsificação de solicitações entre sites (CSRF). Para obter mais informações, consulte a página [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) na documentação da Mozilla.org. para desenvolvedores.
+ Para obter informações sobre como solucionar problemas relacionados com cadernos, sessões e grupos de trabalho do Spark no Athena, consulte [Solucionar problemas do Athena para Spark](notebooks-spark-troubleshooting.md).

# Introdução ao Apache Spark no Amazon Athena
<a name="notebooks-spark-getting-started"></a>

**nota**  
Para a versão de lançamento do Apache Spark versão 3.5, siga o guia de conceitos básicos em [Cadernos do SageMaker](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html). Use este guia para a versão de lançamento do mecanismo Pyspark versão 3.

Para começar a usar o Apache Spark no Amazon Athena, primeiro, você deve criar um grupo de trabalho habilitado para Spark. Depois de alternar para o grupo de trabalho, é possível criar um caderno ou abrir um caderno existente. Quando você abre um caderno no Athena, uma nova sessão é iniciada para ele automaticamente e você pode trabalhar com ele diretamente no editor de cadernos do Athena.

**nota**  
Certifique-se de criar um grupo de trabalho habilitado para Spark antes de tentar criar um caderno.

## Etapa 1: criar um grupo de trabalho habilitado para Spark no Athena
<a name="notebooks-spark-getting-started-creating-a-spark-enabled-workgroup"></a>

É possível usar [grupos de trabalho](workgroups-manage-queries-control-costs.md) no Athena para agrupar usuários, equipes, aplicações ou workloads, além de monitorar custos. Para usar o Apache Spark no Amazon Athena, crie um grupo de trabalho do Amazon Athena que usa um mecanismo Spark.

**nota**  
Grupos de trabalho habilitados para o Apache Spark podem usar o editor de cadernos do Athena, mas não o editor de consultas do Athena. Somente os grupos de trabalho do Athena podem usar o editor de consultas do Athena.

**Para criar um grupo de trabalho habilitado para Spark no Athena**

1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home).

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 página **Workgroups** (Grupos de trabalho), escolha **Create workgroup** (Criar grupo de trabalho).

1. Em **Workgroup name** (Nome do grupo de trabalho), insira um nome para seu grupo de trabalho do Apache Spark.

1. (Opcional) Em **Description** (Descrição), insira uma descrição para seu grupo de trabalho.

1. Em **Analytics engine** (Mecanismo de análise), escolha **Apache Spark**.
**nota**  
Após a criação de um grupo de trabalho, o tipo de mecanismo de análise do grupo de trabalho não poderá ser alterado. Por exemplo, um grupo de trabalho que usa a versão 3 do mecanismo Athena não poderá ser alterado para um grupo de trabalho que usa a versão 3 do mecanismo PySpark. 

1. Para fins deste tutorial, selecione **Turn on example notebook** (Ativar caderno de exemplo). Esse recurso opcional adiciona um caderno de exemplo com o nome `example-notebook-random_string` ao seu grupo de trabalho e adiciona permissões relacionadas ao AWS Glue que o caderno usa para criar, apresentar e excluir tabelas e bancos de dados específicos em sua conta, além de permissões de leitura no Amazon S3 para o conjunto de dados de amostra. Para visualizar as permissões adicionadas, escolha **View additional permissions details** (Apresentar detalhes adicionais das permissões).
**nota**  
 A execução do caderno de exemplo poderá gerar custos adicionais. 

1. Em **Configurações de resultados de cálculos**, escolha entre as seguintes opções:
   + **Create a new S3 bucket** (Criar um novo bucket do S3): essa opção cria um bucket do Amazon S3 em sua conta para os resultados dos cálculos. O nome do bucket tem o formato `account_id-region-athena-results-bucket-alphanumeric_id` e usa as configurações ACLs desabilitadas, o acesso público bloqueado, o controle de versionamento desabilitado e o proprietário do depósito aplicado.
   + **Choose an existing S3 location** (Escolher um local existente do S3): para essa opção, faça o seguinte:
     + Insira o caminho no S3 para um local existente na caixa de pesquisa ou escolha **Browse S3** (Procurar no S3) para escolher um bucket em uma lista.
**nota**  
Ao selecionar um local existente no Amazon S3, não acrescente uma barra (`/`) ao local. Isso faz com que o link para o local dos resultados dos cálculos na [página de detalhes dos cálculo](#notebooks-spark-getting-started-viewing-session-and-calculation-details) direcione para o diretório incorreto. Se isso ocorrer, edite o local dos resultados do grupo de trabalho para remover a barra ao final. 
     + (Opcional) Escolha **View** (Visualizar) para abrir a página **Buckets** do console do Amazon S3, na qual você pode visualizar mais informações sobre o bucket existente escolhido.
     + (Opcional) Em **Expected bucket owner** (Proprietário esperado do bucket), insira o ID da conta da AWS de quem você espera que seja o proprietário do bucket do local de saída dos resultados da consulta. Recomendamos que você escolha essa opção, como uma medida de segurança adicional, sempre que possível. Se o ID da conta do proprietário do bucket não corresponder ao ID especificado, 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*. 
     + (Opcional) Selecione **Assign bucket owner full control over query results** (Atribuir controle total ao proprietário do bucket sobre os resultados da consulta) se o local para os resultados dos cálculos pertencer a outra conta e você desejar conceder controle total sobre os resultados da consulta à outra conta.

1. (Opcional) Escolha **Criptografar resultados de consultas** se quiser que os resultados das consultas sejam criptografados.
   + Em **Tipo de criptografia**, escolha uma das seguintes opções:
     + **SSE\$1S3**: essa opção usa criptografia do lado do servidor (SSE) com chaves gerenciadas pelo Amazon S3.
     + **SSE\$1KMS**: essa opção usa criptografia do lado do servidor (SSE) com chaves gerenciadas pelo AWS KMS. 

       Em **Escolher uma chave do AWS KMS**, escolha uma das seguintes opções.
       + **Usar chave pertencente à AWS**: a chave do AWS KMS pertence e é gerenciada pela AWS. Não há custo adicional para usar essa chave.
       + **Escolher outra chave do AWS KMS (avançada)**: nessa opção, faça uma das seguintes alternativas:
         + Para usar uma chave existente, use a caixa de pesquisa para escolher um AWS KMS ou insira um ARN de chave.
         + Para criar uma chave no console do AWS KMS, escolha **Criar uma chave do AWS KMS**. Seu perfil de execução deve ter permissões para usar a chave que você criar. Após terminar a criação da chave no console do KMS, retorne à página **Criar grupo de trabalho** no console do Athena e use a caixa de pesquisa **Escolher uma chave do AWS KMS ou inserir um ARN** para escolher a chave que você acabou de criar.
**Importante**  
Quando você altera a [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) para um grupo de trabalho, os cadernos gerenciados antes da atualização ainda fazem referência à antiga chave do KMS. Os cadernos gerenciados após a atualização usarão a nova chave do KMS. Para atualizar os cadernos antigos para fazer referência à nova chave do KMS, exporte e importe cada um dos cadernos antigos. Se você excluir a antiga chave do KMS antes de atualizar as referências dos cadernos antigos para a nova chave do KMS, os cadernos antigos não poderão mais ser descriptografados e não poderão ser recuperados.  
Esse comportamento também se aplica a atualizações de [aliases](https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html), que são nomes amigáveis ​​para chaves do KMS. Quando você atualiza um alias de chave do KMS para direcionar para uma nova chave do KMS, os cadernos gerenciados antes da atualização do alias ainda fazem referência à antiga chave do KMS e os cadernos gerenciados após a atualização do alias usam a nova chave do KMS. Considere esses pontos antes de atualizar suas chaves ou aliases do KMS. 

1. Em **Configurações adicionais**, escolha **Usar padrões**. Essa opção ajuda você a começar a usar o grupo de trabalho habilitado para Spark. Quando você usa padrões, o Athena cria um perfil do IAM e um local para os resultados de cálculos no Amazon S3 para você. O nome do perfil do IAM e o local do bucket S3 a serem criados são exibidos na caixa abaixo do cabeçalho **Additional configurations** (Configurações adicionais).

   Se não quiser usar os padrões, prossiga com as etapas da seção [(Opcional) Especificar suas próprias configurações de grupo de trabalho](#notebooks-spark-getting-started-workgroup-configuration) para configurar o grupo de trabalho manualmente.

1. (Opcional) **Tags** (Etiquetas): use essa opção para adicionar etiquetas ao seu grupo de trabalho. Para obter mais informações, consulte [Marcar recursos do Athena com tags](tags.md).

1. Escolha **Create workgroup (Criar grupo de trabalho)**. Uma mensagem informará que o grupo de trabalho foi criado com êxito e o grupo de trabalho aparecerá na lista de grupos de trabalho.

### (Opcional) Especificar suas próprias configurações de grupo de trabalho
<a name="notebooks-spark-getting-started-workgroup-configuration"></a>

Se você deseja especificar o próprio perfil do IAM e o local para os resultados dos cálculos para seu caderno, siga as etapas nesta seção. Se você escolheu **Use defaults** (Usar padrões) para a opção **Additional configurations** (Configurações adicionais), ignore esta seção e vá diretamente para [Etapa 2: abrir o explorador de cadernos e alternar entre grupos de trabalho](#notebooks-spark-getting-started-switching-workgroups-and-opening-notebook-explorer).

O procedimento a seguir pressupõe que você concluiu as etapas 1 a 9 do procedimento **Para criar um grupo de trabalho habilitado para Spark no Athena** na seção anterior.

**Para especificar suas próprias configurações de grupo de trabalho**

1. Se você deseja criar ou usar o próprio perfil do IAM, ou configurar a criptografia de caderno, expanda **IAM role configuration** (Configuração do perfil do IAM).
   + Em **Perfil de serviço**, escolha uma das seguintes opções:
     + **Criar um novo perfil de serviço**: escolha essa opção para que o Athena crie um perfil de serviço para você. Para visualizar as permissões concedidas pelo perfil, selecione **View permission details** (Exibir detalhes da permissão).
     + **Usar um perfil de serviço existente**: no menu suspenso, escolha um perfil existente. O perfil que você escolher deve incluir as permissões na primeira opção. Para obter mais informações sobre permissões para grupos de trabalho habilitados para cadernos, consulte [Solucionar problemas de grupos de trabalho habilitados para Spark](notebooks-spark-troubleshooting-workgroups.md).
   + Em **Notebook and calculation code encryption key management** (Gerenciamento de chave de criptografia para códigos de cálculo e cadernos), escolha uma das opções a seguir:
     + **Criptografar usando chave pertencente à AWS (padrão)**: a chave do AWS KMS pertence e é gerenciada pela AWS. Não há custo adicional para usar essa chave.
     + **Criptografar usando sua própria chave do AWS KMS**: para essa opção, faça uma das seguintes alternativas:
       + Para usar uma chave existente, use a caixa de pesquisa para escolher um AWS KMS ou insira um ARN de chave.
       + Para criar uma chave no console do AWS KMS, escolha **Criar uma chave do AWS KMS**. Seu perfil de execução deve ter permissões para usar a chave que você criar. Após terminar a criação da chave no console do KMS, retorne à página **Criar grupo de trabalho** no console do Athena e use a caixa de pesquisa **Escolher uma chave do AWS KMS ou inserir um ARN** para escolher a chave que você acabou de criar.
**Importante**  
Quando você altera a [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) para um grupo de trabalho, os cadernos gerenciados antes da atualização ainda fazem referência à antiga chave do KMS. Os cadernos gerenciados após a atualização usarão a nova chave do KMS. Para atualizar os cadernos antigos para fazer referência à nova chave do KMS, exporte e importe cada um dos cadernos antigos. Se você excluir a antiga chave do KMS antes de atualizar as referências dos cadernos antigos para a nova chave do KMS, os cadernos antigos não poderão mais ser descriptografados e não poderão ser recuperados.  
Esse comportamento também se aplica a atualizações de [aliases](https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html), que são nomes amigáveis ​​para chaves do KMS. Quando você atualiza um alias de chave do KMS para direcionar para uma nova chave do KMS, os cadernos gerenciados antes da atualização do alias ainda fazem referência à antiga chave do KMS e os cadernos gerenciados após a atualização do alias usam a nova chave do KMS. Considere esses pontos antes de atualizar suas chaves ou aliases do KMS. 

1. <a name="notebook-gs-metrics"></a>(Opcional) **Other settings** (Outras configurações): expanda essa opção para habilitar ou desabilitar a opção **Publish CloudWatch metrics** (Publicar métricas do CloudWatch) para o grupo de trabalho. Esse campo é selecionado por padrão. Para obter mais informações, consulte [Monitorar as métricas do Apache Spark com o CloudWatch](notebooks-spark-metrics.md).

1. (Opcional) **Tags** (Etiquetas): use essa opção para adicionar etiquetas ao seu grupo de trabalho. Para obter mais informações, consulte [Marcar recursos do Athena com tags](tags.md).

1. Escolha **Create workgroup (Criar grupo de trabalho)**. Uma mensagem informará que o grupo de trabalho foi criado com êxito e o grupo de trabalho aparecerá na lista de grupos de trabalho.

## Etapa 2: abrir o explorador de cadernos e alternar entre grupos de trabalho
<a name="notebooks-spark-getting-started-switching-workgroups-and-opening-notebook-explorer"></a>

Antes de poder usar o grupo de trabalho habilitado para Spark que acabou de criar, você deve alternar para o grupo de trabalho. Para alternar os grupos de trabalho habilitados para Spark, você pode usar a opção **Workgroup** (Grupo de trabalho) no explorador de cadernos ou no editor de cadernos.

**nota**  
Antes de começar, verifique se o navegador não bloqueia cookies de terceiros. Qualquer navegador que bloqueie cookies de terceiros por padrão ou graças a uma configuração habilitada pelo usuário impedirá a inicialização dos cadernos. Para mais informações sobre o gerenciamento de cookies, consulte:  
[Chrome](https://support.alertlogic.com/hc/en-us/articles/360018127132-Turn-Off-Block-Third-Party-Cookies-in-Chrome-for-Windows)
[Firefox](https://support.mozilla.org/en-US/kb/third-party-cookies-firefox-tracking-protection)
[Safari](https://support.apple.com/guide/safari/manage-cookies-sfri11471/mac)

**Para abrir o explorador de cadernos e alternar grupos de trabalho**

1. No painel de navegação, escolha **Notebook explorer** (Explorador de cadernos).

1. Use a opção **Workgroup** (Grupo de trabalho) no canto superior direito do console para escolher o grupo de trabalho habilitado para Spark que você criou. O caderno de exemplo é mostrado na lista de cadernos.

   É possível usar o explorador de cadernos das seguintes maneiras:
   + Escolha o nome vinculado de um caderno para abrí-lo em uma nova sessão.
   + Para renomear, excluir ou exportar seu caderno, use o menu **Actions** (Ações).
   + Para importar um arquivo do caderno, escolha **Import file** (Importar arquivo).
   + Para criar um caderno, escolha **Create notebook** (Criar caderno).

## Etapa 3: executar o exemplo de caderno
<a name="notebooks-spark-getting-started-running-the-example-notebook"></a>

O caderno de amostra consulta dados de um conjunto de dados de uma viagem de táxi da cidade de Nova York disponível publicamente. O caderno tem exemplos que mostram como trabalhar com o Spark DataFrames, o Spark SQL e o AWS Glue Data Catalog.

**Para executar o caderno de exemplo**

1. No explorador de cadernos, escolha o nome vinculado ao caderno de exemplo.

   Isso inicia uma sessão do caderno com os parâmetros padrões e abre o caderno no editor de cadernos. Uma mensagem informará que uma nova sessão do Apache Spark foi iniciada usando os parâmetros padrões (máximo de 20 DPUs).

1. Para executar as células em ordem e observar os resultados, escolha o botão **Run** (Executar) uma vez para cada célula do caderno. 
   + Role para baixo para visualizar os resultados e exibir novas células.
   + Para as células que têm cálculos, uma barra de progresso mostra a porcentagem concluída, o tempo decorrido e o tempo restante.
   + O caderno de exemplo cria um banco de dados e uma tabela de amostra em sua conta. A célula final os remove como uma etapa de limpeza.

**nota**  
Se você alterar os nomes de pastas, tabelas ou bancos de dados no caderno de exemplo, certifique-se de que essas alterações sejam refletidas nos perfis do IAM usados. Caso contrário, o caderno poderá apresentar falhas devido a permissões insuficientes. 

## Etapa 4: editar detalhes de sessões
<a name="notebooks-spark-getting-started-editing-session-details"></a>

Depois de iniciar uma sessão de caderno, é possível editar os detalhes da sessão, como formato de tabela, criptografia, tempo limite de inatividade da sessão e o número máximo simultâneo de unidades de processamento de dados (DPUs) que deseja usar. Uma DPU é uma medida relativa do poder de processamento que consiste em uma capacidade computacional de 4 vCPUs e 16 GB de memória.

**Para editar os detalhes da sessão**

1. No editor de cadernos, no menu **Session** (Sessão) no canto superior direito, escolha **Edit session** (Editar sessão).

1. Na caixa de diálogo **Editar detalhes da sessão**, na seção **Propriedades do Spark**, escolha ou insira valores para as seguintes opções:
   + **Formato de tabela adicional**: escolha **Linux Foundation Delta Lake**, **Apache Hudi**, **Apache Iceberg** ou **Personalizado**.
     + Para as opções de tabelas **Delta**, **Hudi** ou **Iceberg**, as propriedades de tabela necessárias para o formato de tabela correspondente são fornecidas automaticamente nas opções **Editar na tabela** e **Editar em JSON**. Para obter mais informações sobre como usar esses formatos de tabela, consulte [Usar formatos de tabela não Hive no Athena para Spark](notebooks-spark-table-formats.md).
     + Para adicionar ou remover propriedades de tabela para **Personalizada** ou outros tipos de tabela, use as opções **Editar na tabela** e **Editar em JSON**.
     + Para a opção **Editar na tabela**, escolha **Adicionar propriedade** para adicionar uma propriedade ou **Remover** para remover uma propriedade. Para inserir os nomes das propriedades e os respectivos valores, use as caixas **Chave** e **Valor**.
     + Na opção **Editar em JSON**, use o editor de texto JSON para editar a configuração diretamente.
       + Para copiar o texto JSON para a área de transferência, escolha **Copiar**.
       + Para remover todo o texto do editor JSON, escolha **Limpar**.
       + Para configurar a quebra de linha ou escolher um tema de cores para o editor JSON, escolha o ícone de configurações (engrenagem).
   + **Ativar a criptografia do Spark**: selecione esta opção para criptografar dados gravados em disco e enviados pelos nós de rede do Spark. Para obter mais informações, consulte [Habilitar a criptografia do Apache Spark](notebooks-spark-encryption.md).

1. Na seção **Parâmetros da sessão**, escolha ou insira valores para as seguintes opções:
   + **Session idle timeout** (Tempo limite de inatividade da sessão): escolha ou insira um valor entre 1 e 480 minutos. O padrão é 20.
   + **Coordinator size** (Tamanho do coordenador): um *coordenador* corresponde a um executor especial que realiza a orquestração do trabalho de processamento e gerencia outros executores em uma sessão do caderno. Atualmente, 1 DPU é o valor padrão e o único possível.
   + **Executor size** (Tamanho do executor): um *executor* corresponde a menor unidade de computação que uma sessão do caderno pode solicitar do Athena. Atualmente, 1 DPU é o valor padrão e o único possível.
   + **Max concurrent value** (Valor simultâneo máximo): o número máximo de DPUs que podem ser executadas simultaneamente. O padrão é 20, o mínimo é 3 e o máximo é 60. Aumentar esse valor não alocará recursos adicionais automaticamente, mas o Athena tentará alocar até o máximo especificado quando a carga computacional exigir e quando os recursos estiverem disponíveis.

1. Escolha **Salvar**.

1. Na solicitação **Confirm edit** (Confirmar edição), escolha **Confirm** (Confirmar).

   O Athena salva seu caderno e inicia uma nova sessão com os parâmetros que você especificou. Uma barra de notificação no editor do caderno informará que uma nova sessão foi iniciada com os parâmetros modificados.
**nota**  
O Athena lembrará suas configurações de sessão para o caderno. Se você editar os parâmetros de uma sessão e, em seguida, encerrá-la, o Athena usará os parâmetros de sessão que você configurou na próxima vez que iniciar uma sessão para o caderno. 

## Etapa 5: visualizar detalhes de sessões e cálculos
<a name="notebooks-spark-getting-started-viewing-session-and-calculation-details"></a>

Após executar o caderno, você poderá visualizar os detalhes da sessão e dos cálculos.

**Para visualizar detalhes da sessão e dos cálculos**

1. No menu **Session** (Sessão) no canto superior direito, escolha **View details** (Exibir detalhes).
   + A guia **Current session** (Sessão atual) apresenta informações sobre a sessão atual, incluindo o ID da sessão, o horário de criação, o status e o grupo de trabalho.
   + A guia **History** (Histórico) lista os IDs das sessões anteriores. Para visualizar os detalhes de uma sessão anterior, escolha a guia **History** (Histórico) e, em seguida, escolha um ID de sessão na lista.
   + A seção **Calculations** (Cálculos) apresenta uma lista dos cálculos executados na sessão.

1. Para visualizar os detalhes de um cálculo, escolha o ID do cálculo.

1. Na página **Calculation details** (Detalhes do cálculo), você pode fazer o seguinte:
   + Para visualizar o código para o cálculo, consulte a seção **Code** (Código).
   + Para visualizar os resultados do cálculo, selecione a guia **Results** (Resultados).
   + Para baixar dos resultados que você visualiza em formato de texto, escolha **Download results** (Fazer download dos resultados).
   + Para visualizar informações sobre os resultados dos cálculos no Amazon S3, escolha **View in S3** (Visualizar no S3).

## Etapa 6: encerrar a sessão
<a name="notebooks-spark-getting-started-terminating-a-session"></a>

**Para encerrar uma sessão de caderno**

1. No editor de cadernos, no menu **Session** (Sessão) no canto superior direito, escolha **Terminate** (Encerrar).

1. Na solicitação **Confirm session termination** (Confirmar encerramento da sessão), escolha **Confirm** (Confirmar). Seu caderno será salvo e você retornará ao editor de cadernos.

**nota**  
Fechar uma guia do caderno no editor de cadernos não encerrará por si só a sessão de um caderno ativo. Se você deseja garantir que a sessão seja encerrada, use a opção **Terminate** (Encerrar) em **Session** (Sessão).

## Etapa 7: criar seu próprio caderno
<a name="notebooks-spark-getting-started-creating-your-own-notebook"></a>

Após a criação de um grupo de trabalho do Athena habilitado para Spark, é possível criar seu próprio caderno.

**Para criar um caderno**

1. Se o painel de navegação do console não estiver visível, escolha o menu de expansão à esquerda.

1. No painel de navegação do console do Athena, escolha **Notebook explorer** (Explorador de cadernos) ou **Notebook editor** (Editor de cadernos).

1. Execute um destes procedimentos:
   + No **Notebook explorer** (Explorador de cadernos), escolha **Create notebook** (Criar caderno).
   + No **Notebook editor** (Editor de cadernos), escolha **Create notebook** (Criar caderno) ou selecione o ícone de adição (**\$1**) para adicionar um caderno.

1. Na caixa de diálogo **Create notebook** (Criar caderno), em **Notebook name** (Nome do caderno), insira um nome.

1. (Opcional) Expanda **Propriedades do Spark** e escolha ou insira valores para as seguintes opções:
   + **Formato de tabela adicional**: escolha **Linux Foundation Delta Lake**, **Apache Hudi**, **Apache Iceberg** ou **Personalizado**.
     + Para as opções de tabelas **Delta**, **Hudi** ou **Iceberg**, as propriedades de tabela necessárias para o formato de tabela correspondente são fornecidas automaticamente nas opções **Editar na tabela** e **Editar em JSON**. Para obter mais informações sobre como usar esses formatos de tabela, consulte [Usar formatos de tabela não Hive no Athena para Spark](notebooks-spark-table-formats.md).
     + Para adicionar ou remover propriedades de tabela para **Personalizada** ou outros tipos de tabela, use as opções **Editar na tabela** e **Editar em JSON**.
     + Para a opção **Editar na tabela**, escolha **Adicionar propriedade** para adicionar uma propriedade ou **Remover** para remover uma propriedade. Para inserir os nomes das propriedades e os respectivos valores, use as caixas **Chave** e **Valor**.
     + Na opção **Editar em JSON**, use o editor de texto JSON para editar a configuração diretamente.
       + Para copiar o texto JSON para a área de transferência, escolha **Copiar**.
       + Para remover todo o texto do editor JSON, escolha **Limpar**.
       + Para configurar a quebra de linha ou escolher um tema de cores para o editor JSON, escolha o ícone de configurações (engrenagem).
   + **Ativar a criptografia do Spark**: selecione esta opção para criptografar dados gravados em disco e enviados pelos nós de rede do Spark. Para obter mais informações, consulte [Habilitar a criptografia do Apache Spark](notebooks-spark-encryption.md).

1. (Opcional) Expanda **Session parameters** (Parâmetros da sessão) e, em seguida, escolha ou insira valores para as opções a seguir:
   + **Session idle timeout** (Tempo limite de inatividade da sessão): escolha ou insira um valor entre 1 e 480 minutos. O padrão é 20.
   + **Coordinator size** (Tamanho do coordenador): um *coordenador* corresponde a um executor especial que realiza a orquestração do trabalho de processamento e gerencia outros executores em uma sessão do caderno. Atualmente, 1 DPU é o valor padrão e o único possível. Uma DPU (unidade de processamento de dados) corresponde a uma medida relativa de poder de processamento que consiste em 4 vCPUs de capacidade computacional e 16 GB de memória.
   + **Executor size** (Tamanho do executor): um *executor* corresponde a menor unidade de computação que uma sessão do caderno pode solicitar do Athena. Atualmente, 1 DPU é o valor padrão e o único possível.
   + **Max concurrent value** (Valor simultâneo máximo): o número máximo de DPUs que podem ser executadas simultaneamente. O padrão é 20 e o máximo é 60. Aumentar esse valor não alocará recursos adicionais automaticamente, mas o Athena tentará alocar até o máximo especificado quando a carga computacional exigir e quando os recursos estiverem disponíveis.

1. Escolha **Criar**. Seu caderno será aberto em uma nova sessão no editor de cadernos.

Para obter mais informações sobre gerenciamento de arquivos de cadernos, consulte [Gerenciar arquivos de cadernos](notebooks-spark-managing.md).

# Gerenciar arquivos de cadernos
<a name="notebooks-spark-managing"></a>

**nota**  
O editor do caderno do Athena é compatível com a versão 3 do mecanismo Pyspark. Para usar cadernos com a versão 3.5 do Apache Spark, consulte [Cadernos do SageMaker](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html).

Além de usar o explorador de cadernos para [criar](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook) cadernos, você pode usá-lo também para abrir, renomear, excluir, exportar ou importar cadernos ou para visualizar o histórico da sessão para um caderno.

**Para abrir um caderno criado anteriormente**

1. Se o painel de navegação do console não estiver visível, escolha o menu de expansão à esquerda.

1. No painel de navegação do console do Athena, escolha **Notebook editor** (Editor de cadernos) ou **Notebook explorer** (Explorador de cadernos).

1. Execute um destes procedimentos:
   + No **Notebook editor** (Editor de cadernos), escolha um caderno na lista **Recent notebooks** (Cadernos recentes) ou **Saved notebooks** (Cadernos salvos). O caderno será aberto em uma nova sessão.
   + No **Notebook explorer** (Explorador de cadernos), escolha o nome de um caderno na lista. O caderno será aberto em uma nova sessão.

**Para renomear um caderno**

1. [Encerre](notebooks-spark-getting-started.md#notebooks-spark-getting-started-terminating-a-session) todas as sessões ativas dos cadernos que deseja renomear. As sessões ativas dos cadernos devem ser encerradas antes que você possa renomeá-los.

1. Abra o **Notebook explorer** (Explorador de cadernos).

1. Na lista **Notebooks** (Cadernos), selecione o botão de opção do caderno que deseja renomear.

1. A partir do menu **Actions** (Ações), escolha **Rename** (Renomear).

1. Na solicitação **Rename notebook** (Renomear caderno), digite o novo nome e, em seguida, selecione **Save** (Salvar). O novo nome do caderno aparecerá na lista de cadernos.

**Para excluir um caderno**

1. [Encerre](notebooks-spark-getting-started.md#notebooks-spark-getting-started-terminating-a-session) todas as sessões ativas dos cadernos que deseja excluir. As sessões ativas dos cadernos devem ser encerradas antes que você possa excluí-los.

1. Abra o **Notebook explorer** (Explorador de cadernos).

1. Na lista **Notebooks** (Cadernos), selecione o botão de opção do caderno que deseja excluir.

1. No menu **Actions (Ações)**, escolha **Delete (Excluir)**.

1. Na solicitação **Delete notebook?** (Excluir caderno?), insira o nome do caderno e, em seguida, selecione **Delete** (Excluir) para confirmar a exclusão. O nome do caderno será removido da lista de cadernos.

**Para exportar um caderno**

1. Abra o **Notebook explorer** (Explorador de cadernos).

1. Na lista **Notebooks** (Cadernos), selecione o botão de opção do caderno que deseja exportar.

1. A partir do menu **Actions** (Ações), escolha **Export** (Exportar).

**Para importar um caderno**

1. Abra o **Notebook explorer** (Explorador de cadernos).

1. Escolha **Import file** (Importar arquivo).

1. Navegue até o local em que se encontra o arquivo que deseja importar em seu computador local e, em seguida, escolha **Open** (Abrir). O caderno importado aparecerá na lista de cadernos.

**Para visualizar o histórico da sessão para um caderno**

1. Abra o **Notebook explorer** (Explorador de cadernos).

1. Na lista **Notebooks** (Cadernos), selecione o botão de opção do caderno cujo histórico de sessão você deseja visualizar.

1. A partir do menu **Actions** (Ações), escolha **Session history** (Histórico da sessão).

1. Na guia **History** (Histórico), escolha um **Session ID** (ID de sessão) para visualizar as informações sobre a sessão e seus cálculos.

# Usar o editor de cadernos do Athena
<a name="notebooks-spark-editor"></a>

**nota**  
O editor do caderno do Athena é compatível com a versão 3 do mecanismo Pyspark. Para usar cadernos com a versão 3.5 do Apache Spark, consulte [Cadernos do SageMaker](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html).

Você gerencia seus cadernos no explorador de cadernos do Athena e os edita e executa em sessões usando o editor de cadernos do Athena. É possível configurar o uso da DPU para suas sessões de cadernos de acordo com seus requisitos.

Ao interromper um caderno, você encerra a sessão associada. Todos os arquivos serão salvos, mas as alterações em andamento nas variáveis, funções e classes declaradas serão perdidas. Quando você reinicia o caderno, o Athena recarrega os arquivos do caderno e você pode executar o código novamente.

O editor de cadernos do Athena é um ambiente interativo para gravar e executar códigos. As seções a seguir descrevem os recursos do ambiente.

## Entender as sessões e os cálculos de cadernos
<a name="notebooks-spark-sessions-and-calculations"></a>

Cada caderno está associado a um único kernel do Python e executa o código Python. Um caderno pode ter uma ou mais células que contêm comandos. Para executar as células em um caderno, primeiro crie uma sessão para ele. As sessões acompanham as variáveis ​​e o estado dos cadernos. 

Executar uma célula em um caderno significa executar um cálculo na sessão atual. Os cálculos avançam no estado do caderno e podem executar tarefas como leitura do Amazon S3 ou gravação para outros armazenamentos de dados. Enquanto uma sessão estiver em execução, os cálculos usam e modificam o estado que é mantido para o caderno.

Quando você não precisar mais do estado, poderá encerrar uma sessão. Ao encerrar uma sessão, o caderno permanecerá, mas as variáveis e outras informações de estado serão destruídas. Se você precisar trabalhar em diversos projetos ao mesmo tempo, poderá criar uma sessão para cada projeto, e as sessões serão independentes umas das outras.

As sessões têm capacidade de computação dedicada, que é medida em DPU. Ao criar uma sessão, é possível atribuir à sessão um número de DPUs. Sessões diferentes podem ter capacidades diferentes, dependendo dos requisitos para a tarefa.

## Alternar entre o modo de comando e o modo de edição
<a name="notebooks-spark-command-mode-vs-edit-mode"></a>

O editor de cadernos tem uma interface de usuário modal: um modo de edição para inserir texto em uma célula e um modo de comando para emitir comandos para o próprio editor, como copiar, colar ou executar.

Para usar o modo de edição e o modo de comando, você pode executar as tarefas a seguir:
+ Para entrar no modo de edição, pressione **ENTER** ou selecione uma célula. Quando uma célula está no modo de edição, ela tem uma margem esquerda na cor verde.
+ Para entrar no modo de comando, pressione **ESC** ou clique na parte exterior de uma célula. Observe que os comandos geralmente se aplicam somente à célula selecionada no momento, não a todas as células. Quando o editor está no modo de comando, a célula tem uma margem esquerda na cor azul.
+ No modo de comando, é possível usar atalhos de teclado e o menu acima do editor, mas não é possível inserir texto em células individuais.
+ Para selecionar uma célula, escolha a célula.
+ Para selecionar todas as células, pressione **Ctrl\$1A** (Windows) ou **Cmd\$1A** (Mac).

## Usar ações no menu do editor de cadernos
<a name="notebooks-spark-notebook-editor-menu"></a>

Os ícones no menu presente na parte superior do editor de cadernos oferecem as seguintes opções:
+ **Salvar**: salva o estado atual do caderno.
+ **Inserir célula abaixo**: adiciona uma nova célula (vazia) abaixo da célula selecionada no momento.
+ **Recortar células selecionadas**: remove a célula selecionada de sua localização atual e copia a célula para a memória.
+ **Copiar células selecionadas**: copia a célula selecionada para a memória.
+ **Colar células abaixo**: cola a célula copiada abaixo da célula atual.
+ **Mover as células selecionadas para cima**: move a célula atual acima da célula que está na posição acima.
+ **Mover as células selecionadas para baixo**: move a célula atual abaixo da célula que está na posição abaixo.
+ **Executar**: executa a célula atual (selecionada). A saída é exibida logo abaixo da célula atual.
+ **Executar tudo**: executa todas as células presentes no caderno. A saída para cada célula é exibida logo abaixo das respectivas células.
+ **Parar (interromper o kernel)**: interrompe o caderno atual ao interromper o kernel.
+ **Opção de formato**: seleciona o formato da célula, que pode ser um dos seguintes:
  + **Código**: use para códigos do Python (padrão).
  + **Markdown**: use para inserir texto no formato [markdown estilo GitHub](https://docs.github.com/en/get-started/writing-on-github). Para renderizar o markdown, realize a execução da célula.
  + **Raw NBConvert**: use para inserir texto em um formato não modificado. As células marcadas como **Raw NBConvert** podem ser convertidas em um formato diferente, como HTML, pela ferramenta de linha de comando [nbconvert](https://nbconvert.readthedocs.io/en/latest/usage.html) do Jupyter.
+ **Cabeçalho**: use para alterar o nível do cabeçalho da célula.
+ **Paleta de comandos**: contém comandos do caderno Jupyter e seus atalhos de teclado. Para obter mais informações sobre os atalhos de teclado, consulte as seções posteriores neste documento.
+ **Sessão**: use as opções desse menu para [visualizar](notebooks-spark-getting-started.md#notebooks-spark-getting-started-viewing-session-and-calculation-details) os detalhes de uma sessão, [editar os parâmetros da sessão](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details) ou [encerrá-la](notebooks-spark-getting-started.md#notebooks-spark-getting-started-terminating-a-session). 

## Usar os atalhos de teclado do modo de comando para aumentar a produtividade
<a name="notebooks-spark-command-mode-keyboard-shortcuts"></a>

A seguir estão alguns atalhos de teclado conhecidos do modo de comando do editor de cadernos. Esses atalhos estão disponíveis após pressionar **ESC** para entrar no modo de comando. Para visualizar uma lista completa de comandos disponíveis no editor, pressione **ESC \$1 H**.


****  

| Chave | Ação | 
| --- | --- | 
| 1 - 6 | Alterar o tipo de célula para markdown e definir o nível do cabeçalho para o número digitado | 
| a | Criar uma célula acima da célula atual | 
| b | Criar uma célula abaixo da célula atual | 
| c | Copiar a célula atual para a memória | 
| d d | Excluir a célula atual | 
| h | Exibir a tela de ajuda para os atalhos de teclado | 
| j | Ir uma célula abaixo | 
| k | Ir uma célula acima | 
| m | Alterar o formato atual da célula para markdown | 
| r | Alterar o formato atual da célula para raw | 
| s | Salvar o caderno | 
| v | Colar o conteúdo da memória na célula atual | 
| x | Recortar a célula ou as células selecionadas | 
| y | Alterar o formato da célula para código | 
| z | Desfazer | 
| Ctrl\$1Enter  | Executar a célula atual e entrar no modo de comando | 
| Shift\$1Enter ou Alt\$1Enter | Executar a célula atual e criar uma nova célula abaixo da saída, além de inserir a nova célula no modo de edição | 
| Space | Uma página abaixo | 
| Shift\$1Space | Uma página acima | 
| Shift \$1 L | Alternar a visibilidade dos números de linha nas células | 

## Personalizar os atalhos do modo de comando
<a name="notebooks-spark-editing-command-mode-shortcuts"></a>

O editor de cadernos tem a opção para personalizar os atalhos de teclado do modo de comando.

**Para editar atalhos do modo de comando**

1. No menu do editor de cadernos, escolha a **Command palette** (Paleta de comandos).

1. Na paleta de comandos, escolha o comando **Edit command mode keyboard shortcuts** (Editar atalhos de teclado do modo de comando).

1. Use a interface **Edit command mode shortcuts** (Editar atalhos do modo de comando) para mapear ou mapear novamente os comandos que você deseja para o teclado.

   Para visualizar as instruções para edição dos atalhos do modo de comando, role até a parte inferior da tela do **Edit command mode shortcuts** (Editar atalhos do modo de comando).

Para obter informações sobre como usar comandos magic no Athena para Apache Spark, consulte [Usar comandos mágicos](notebooks-spark-magics.md).

**Topics**
+ [Entender as sessões e os cálculos de cadernos](#notebooks-spark-sessions-and-calculations)
+ [Alternar entre o modo de comando e o modo de edição](#notebooks-spark-command-mode-vs-edit-mode)
+ [Usar ações no menu do editor de cadernos](#notebooks-spark-notebook-editor-menu)
+ [Usar os atalhos de teclado do modo de comando para aumentar a produtividade](#notebooks-spark-command-mode-keyboard-shortcuts)
+ [Personalizar os atalhos do modo de comando](#notebooks-spark-editing-command-mode-shortcuts)
+ [Usar comandos mágicos](notebooks-spark-magics.md)

# Usar comandos mágicos
<a name="notebooks-spark-magics"></a>

Comandos mágicos, ou mágicas, correspondem a comandos especiais que você pode executar em uma célula do caderno. Por exemplo, `%env` apresenta as variáveis de ambiente em uma sessão do caderno. O Athena oferece suporte para as funções mágicas no IPython 6.0.3. 

Esta seção apresenta alguns dos principais comandos magic no Athena para Apache Spark.
+  Para visualizar uma lista de comandos magic no Athena, execute o comando **%lsmagic** em uma célula de caderno. 
+ Para obter informações sobre como usar magic para criar grafos em cadernos do Athena, consulte [Usar mágica para criar gráficos de dados](notebooks-spark-magics-graphs.md).
+ Para obter informações sobre outros comandos magic, consulte [Comandos magic integrados](https://ipython.readthedocs.io/en/stable/interactive/magics.html) na documentação do IPython.

**nota**  
Atualmente, o comando `%pip` apresenta falhas quando é executado. Esse é um problema conhecido. 

**Topics**
+ [Magics de células](notebooks-spark-magics-cell-magics.md)
+ [Magics de linha](notebooks-spark-magics-line-magics.md)
+ [Magics de grafos](notebooks-spark-magics-graphs.md)

# Usar mágica de célula
<a name="notebooks-spark-magics-cell-magics"></a>

Mágicas que são gravadas em diversas linhas são precedidas por um sinal de porcentagem duplo (`%%`) e são chamadas de funções mágicas de células ou mágicas de células.

## %%sql
<a name="notebooks-spark-magics-sql"></a>

O magic de células permite executar instruções SQL diretamente sem precisar decorá-las com a instrução SQL do Spark. O comando também exibe a saída chamando implicitamente `.show()` no quadro de dados retornado.

![\[Usar o %%sql.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/notebooks-spark-magics-1.png)


O comando `%%sql` trunca automaticamente as saídas da coluna para uma largura de 20 caracteres. Essa definição não é configurável no momento. Para contornar essa limitação, use a sintaxe completa a seguir e modifique os parâmetros do método `show` adequadamente. 

```
spark.sql("""YOUR_SQL""").show(n=number, truncate=number, vertical=bool)
```
+ **n** `int`, opcional. O número de linhas a serem exibidas.
+ **truncar**: `bool` ou `int`, opcional. Se `true`, trunca strings com mais de 20 caracteres. Quando definido como um número maior que 1, trunca strings de caracteres longas até o comprimento especificado e alinha as células à direita.
+ **vertical**: `bool`, opcional. Se `true`, imprime as linhas de saída verticalmente (uma linha por valor de coluna).

# Usar mágica de linha
<a name="notebooks-spark-magics-line-magics"></a>

Mágicas que estão em uma única linha são precedidas por um sinal de porcentagem (`%`) e são chamadas de funções mágicas de linha ou mágicas de linha.

## %help
<a name="notebooks-spark-magics-help"></a>

Exibe descrições dos comandos magic disponíveis.

![\[Usar o %help.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/notebooks-spark-magics-2.png)


## %list\$1sessions
<a name="notebooks-spark-magics-list_sessions"></a>

Lista as sessões associadas ao caderno. As informações de cada sessão incluem o ID da sessão, o status da sessão e a data e hora em que a sessão iniciou e terminou.

![\[Usar o %list_sessions.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/notebooks-spark-magics-3.png)


## %session\$1id
<a name="notebooks-spark-magics-session_id"></a>

Recupera o ID da sessão atual.

![\[Usar o session_id.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/notebooks-spark-magics-4.png)


## %set\$1log\$1level
<a name="notebooks-spark-magics-set_log_level"></a>

Define ou redefine o logger para usar o nível de log especificado. Os valores possíveis são `DEBUG`, `ERROR`, `FATAL`,`INFO` e `WARN` ou `WARNING`. Os valores devem estar em letras maiúsculas e não devem estar delimitados entre aspas simples ou duplas.

![\[Usar o %set_log_level.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/notebooks-spark-magics-5.png)


## %status
<a name="notebooks-spark-magics-status"></a>

Descreve a sessão atual. A saída inclui o ID da sessão, o estado da sessão, o nome do grupo de trabalho, a versão do mecanismo PySpark e a hora de início da sessão. Esse comando magic requer uma sessão ativa para recuperar os detalhes da sessão.

Os seguintes valores de status são possíveis:

**CREATING**: a sessão está sendo iniciada, incluindo a aquisição de recursos.

**CREATED**: a sessão foi iniciada.

**IDLE**: a sessão pode aceitar um cálculo.

**BUSY**: a sessão está processando outra tarefa e não pode aceitar um cálculo.

**TERMINATING**: a sessão está no processo de desligamento.

**TERMINATED**: a sessão e os respectivos recursos não estão mais em execução.

**DEGRADED**: a sessão não tem coordenadores íntegros.

**FAILED**: devido a uma falha, a sessão e os respectivos recursos não estão mais em execução.

![\[Usar o %status.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/notebooks-spark-magics-6.png)


# Usar mágica para criar gráficos de dados
<a name="notebooks-spark-magics-graphs"></a>

Os magics de linha desta seção são especializados em renderizar dados para tipos específicos de dados ou em conjunto com bibliotecas de grafos.

## %table
<a name="notebooks-spark-magics-graphs-table"></a>

Use o comando magic `%table` para exibir dados do quadro de dados em formato de tabela.

O exemplo a seguir cria um quadro de dados com duas colunas e três linhas de dados e exibe os dados em formato de tabela.

![\[Usar o comando magic %table.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/notebooks-spark-magics-graphs-1.png)


## %matplot
<a name="notebooks-spark-magics-graphs-matplot"></a>

[Matplotlib](https://matplotlib.org/) é uma biblioteca completa para criar visualizações estáticas, animadas e interativas em Python. Você pode usar o comando magic `%matplot` para criar um grafo depois de importar a biblioteca matplotlib para uma célula do caderno.

O exemplo a seguir importa a biblioteca matplotlib, cria um conjunto de coordenadas x e y e usa o comando magic `%matplot` para criar um grafo dos pontos.

```
import matplotlib.pyplot as plt 
x=[3,4,5,6,7,8,9,10,11,12] 
y= [9,16,25,36,49,64,81,100,121,144] 
plt.plot(x,y) 
%matplot plt
```

![\[Usar o comando magic %matplot.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/notebooks-spark-magics-graphs-2.png)


### Usar as bibliotecas matplotlib e seaborn juntas
<a name="notebooks-spark-magics-graphs-using-the-matplotlib-and-seaborn-libraries-together"></a>

[Seaborn](https://seaborn.pydata.org/tutorial/introduction) é uma biblioteca para criação de gráficos estatísticos em Python. Baseia-se no matplotlib e integra-se estreitamente às estruturas de dados [pandas](https://pandas.pydata.org/) (análise de dados Python). Também é possível usar o comando magic `%matplot` para renderizar dados seaborn.

O exemplo a seguir usa as bibliotecas matplotlib e seaborn para criar um grafo de barras simples.

```
import matplotlib.pyplot as plt 
import seaborn as sns 

x = ['A', 'B', 'C'] 
y = [1, 5, 3] 

sns.barplot(x, y) 
%matplot plt
```

![\[Usar %matplot para renderizar dados seaborn.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/notebooks-spark-magics-graphs-3.png)


## %plotly
<a name="notebooks-spark-magics-graphs-plotly"></a>

[Plotly](https://plotly.com/python/) é uma biblioteca de grafos de código aberto para Python que você pode usar para criar grafos interativos. Use o comando magic `%ploty` para renderizar dados ploty.

O exemplo a seguir usa as bibliotecas [StringIO](https://docs.python.org/3.13/library/io.html#io.StringIO), plotly e pandas em dados de preços de ações para criar um grafo da atividade de ações de fevereiro e março de 2015.

```
from io import StringIO 
csvString = """ 
Date,AAPL.Open,AAPL.High,AAPL.Low,AAPL.Close,AAPL.Volume,AAPL.Adjusted,dn,mavg,up,direction 
2015-02-17,127.489998,128.880005,126.919998,127.830002,63152400,122.905254,106.7410523,117.9276669,129.1142814,Increasing 
2015-02-18,127.629997,128.779999,127.449997,128.720001,44891700,123.760965,107.842423,118.9403335,130.0382439,Increasing 
2015-02-19,128.479996,129.029999,128.330002,128.449997,37362400,123.501363,108.8942449,119.8891668,130.8840887,Decreasing 
2015-02-20,128.619995,129.5,128.050003,129.5,48948400,124.510914,109.7854494,120.7635001,131.7415509,Increasing 
2015-02-23,130.020004,133,129.660004,133,70974100,127.876074,110.3725162,121.7201668,133.0678174,Increasing 
2015-02-24,132.940002,133.600006,131.169998,132.169998,69228100,127.078049,111.0948689,122.6648335,134.2347981,Decreasing 
2015-02-25,131.559998,131.600006,128.149994,128.789993,74711700,123.828261,113.2119183,123.6296667,134.0474151,Decreasing 
2015-02-26,128.789993,130.869995,126.610001,130.419998,91287500,125.395469,114.1652991,124.2823333,134.3993674,Increasing 
2015-02-27,130,130.570007,128.240005,128.460007,62014800,123.510987,114.9668484,124.8426669,134.7184854,Decreasing 
2015-03-02,129.25,130.279999,128.300003,129.089996,48096700,124.116706,115.8770904,125.4036668,134.9302432,Decreasing 
2015-03-03,128.960007,129.520004,128.089996,129.360001,37816300,124.376308,116.9535132,125.9551669,134.9568205,Increasing 
2015-03-04,129.100006,129.559998,128.320007,128.539993,31666300,123.587892,118.0874253,126.4730002,134.8585751,Decreasing 
2015-03-05,128.580002,128.75,125.760002,126.410004,56517100,121.539962,119.1048311,126.848667,134.5925029,Decreasing 
2015-03-06,128.399994,129.369995,126.260002,126.599998,72842100,121.722637,120.190797,127.2288335,134.26687,Decreasing 
2015-03-09,127.959999,129.570007,125.059998,127.139999,88528500,122.241834,121.6289771,127.631167,133.6333568,Decreasing 
2015-03-10,126.410004,127.220001,123.800003,124.510002,68856600,119.71316,123.1164763,127.9235004,132.7305246,Decreasing 
""" 
csvStringIO = StringIO(csvString) 
 
from io import StringIO 
import plotly.graph_objects as go 
import pandas as pd 
from datetime import datetime 
df = pd.read_csv(csvStringIO) 
fig = go.Figure(data=[go.Candlestick(x=df['Date'], 
open=df['AAPL.Open'], 
high=df['AAPL.High'], 
low=df['AAPL.Low'], 
close=df['AAPL.Close'])]) 
%plotly fig
```

![\[Usar o comando magic %ploty.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/notebooks-spark-magics-graphs-4.png)


# Usar formatos de tabela não Hive no Athena para Spark
<a name="notebooks-spark-table-formats"></a>

**nota**  
Esta página refere-se ao uso de bibliotecas Python na versão de lançamento do mecanismo Pyspark versão 3. Consulte [Amazon EMR 7.12](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-7120-release.html) para ver as versões compatíveis em formato aberto de tabela.

Ao trabalhar com sessões e cadernos no Athena para Spark, é possível usar tabelas do Linux Foundation Delta Lake, do Apache Hudi e do Apache Iceberg, além das tabelas do Apache Hive.

## Considerações e limitações
<a name="notebooks-spark-table-formats-considerations-and-limitations"></a>

Ao usar formatos de tabela que não sejam do Apache Hive com o Athena para Spark, considere os seguintes pontos:
+ Além do Apache Hive, somente um formato de tabela por caderno é compatível. Para usar vários formatos de tabela no Athena para Spark, crie um caderno separado para cada formato de tabela. Para obter informações sobre como criar cadernos no Athena para Spark, consulte [Etapa 7: criar seu próprio caderno](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook).
+ Os formatos de tabela Delta Lake, Hudi e Iceberg foram testados no Athena para Spark usando o AWS Glue como o metastore. Talvez seja possível usar outros metastores, mas não há suporte para esse uso atualmente.
+ Para usar os outros formatos de tabela, substitua a propriedade `spark_catalog` padrão, conforme indicado no console do Athena e nesta documentação. Esses catálogos que não são do Hive podem ler tabelas do Hive, além de seus próprios formatos de tabela.

## Versões de tabela
<a name="notebooks-spark-table-formats-versions"></a>

A tabela a seguir mostra as versões de tabela que não são do Hive compatíveis com o Amazon Athena para Apache Spark.


****  

| Formato da tabela | Versão com suporte | 
| --- | --- | 
| Apache Iceberg | 1.2.1 | 
| Apache Hudi | 0.13 | 
| Linux Foundation Delta Lake | 2.0.2 | 

No Athena para Spark, esses arquivos de formato de tabela `.jar` e suas dependências são carregados no caminho de classe dos drivers e executores do Spark.

Para uma postagem no *blog do AWS Big Data* que mostra como trabalhar com os formatos de tabela Iceberg, Hudi e Delta Lake usando o Spark SQL nos notebooks do Amazon Athena, consulte [Use Amazon Athena with Spark SQL for your open-source transactional table formats](https://aws.amazon.com/blogs/big-data/use-amazon-athena-with-spark-sql-for-your-open-source-transactional-table-formats/).

**Topics**
+ [Considerações e limitações](#notebooks-spark-table-formats-considerations-and-limitations)
+ [Versões de tabela](#notebooks-spark-table-formats-versions)
+ [Iceberg](notebooks-spark-table-formats-apache-iceberg.md)
+ [Hudi](notebooks-spark-table-formats-apache-hudi.md)
+ [Delta Lake](notebooks-spark-table-formats-linux-foundation-delta-lake.md)

# Usar tabelas do Apache Iceberg no Athena para Spark
<a name="notebooks-spark-table-formats-apache-iceberg"></a>

O [Apache Iceberg](https://iceberg.apache.org/) é um formato de tabela aberta para grandes conjuntos de dados no Amazon Simple Storage Service (Amazon S3). Ele fornece performance rápida de consultas em tabelas grandes, confirmações atômicas, gravações simultâneas e evolução de tabelas compatível com SQL.

Para usar tabelas do Apache Iceberg no Athena para Spark, configure as propriedades do Spark a seguir. Essas propriedades são configuradas por padrão no console do Athena para Spark quando você escolhe Apache Iceberg como formato de tabela. Para obter as etapas, consulte [Etapa 4: editar detalhes de sessões](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details) ou [Etapa 7: criar seu próprio caderno](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook).

```
"spark.sql.catalog.spark_catalog": "org.apache.iceberg.spark.SparkSessionCatalog",
"spark.sql.catalog.spark_catalog.catalog-impl": "org.apache.iceberg.aws.glue.GlueCatalog",
"spark.sql.catalog.spark_catalog.io-impl": "org.apache.iceberg.aws.s3.S3FileIO",
"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"
```

O procedimento a seguir mostra como usar uma tabela do Apache Iceberg em um caderno do Athena para Spark. Execute cada etapa em uma nova célula no caderno.

**Para usar tabelas do Apache Iceberg no Athena para Spark**

1. Defina as constantes a serem usadas no caderno.

   ```
   DB_NAME = "NEW_DB_NAME"
   TABLE_NAME = "NEW_TABLE_NAME"
   TABLE_S3_LOCATION = "s3://amzn-s3-demo-bucket"
   ```

1. Crie um [DataFrame](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/dataframe.html) do Apache Spark.

   ```
   columns = ["language","users_count"]
   data = [("Golang", 3000)]
   df = spark.createDataFrame(data, columns)
   ```

1. Crie um banco de dados.

   ```
   spark.sql("CREATE DATABASE {} LOCATION '{}'".format(DB_NAME, TABLE_S3_LOCATION))
   ```

1. Crie uma tabela vazia do Apache Iceberg.

   ```
   spark.sql("""
   CREATE TABLE {}.{} (
   language string,
   users_count int
   ) USING ICEBERG
   """.format(DB_NAME, TABLE_NAME))
   ```

1. Insira uma linha de dados na tabela.

   ```
   spark.sql("""INSERT INTO {}.{} VALUES ('Golang', 3000)""".format(DB_NAME, TABLE_NAME))
   ```

1. Confirme se é possível consultar a nova tabela.

   ```
   spark.sql("SELECT * FROM {}.{}".format(DB_NAME, TABLE_NAME)).show()
   ```

Para obter mais informações e exemplos sobre como trabalhar com tabelas DataFrames e Iceberg do Spark, consulte [Spark Queries](https://iceberg.apache.org/docs/latest/spark-queries/) na documentação do Apache Iceberg.

# Usar tabelas do Apache Hudi no Athena para Spark
<a name="notebooks-spark-table-formats-apache-hudi"></a>

O [https://hudi.apache.org/](https://hudi.apache.org/) é um framework de gerenciamento de dados de código aberto que simplifica o processamento incremental de dados. As ações de inserção, atualização, upsert e exclusão em nível de registro são processadas com maior precisão, o que reduz a sobrecarga.

Para usar tabelas do Apache Hudi no Athena para Spark, configure as propriedades do Spark a seguir. Essas propriedades são configuradas por padrão no console do Athena para Spark quando você escolhe Apache Hudi como formato de tabela. Para obter as etapas, consulte [Etapa 4: editar detalhes de sessões](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details) ou [Etapa 7: criar seu próprio caderno](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook).

```
"spark.sql.catalog.spark_catalog": "org.apache.spark.sql.hudi.catalog.HoodieCatalog",
"spark.serializer": "org.apache.spark.serializer.KryoSerializer",
"spark.sql.extensions": "org.apache.spark.sql.hudi.HoodieSparkSessionExtension"
```

O procedimento a seguir mostra como usar uma tabela do Apache Hudi em um caderno do Athena para Spark. Execute cada etapa em uma nova célula no caderno.

**Para usar tabelas do Apache Hudi no Athena para Spark**

1. Defina as constantes a serem usadas no caderno.

   ```
   DB_NAME = "NEW_DB_NAME"
   TABLE_NAME = "NEW_TABLE_NAME"
   TABLE_S3_LOCATION = "s3://amzn-s3-demo-bucket"
   ```

1. Crie um [DataFrame](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/dataframe.html) do Apache Spark.

   ```
   columns = ["language","users_count"]
   data = [("Golang", 3000)]
   df = spark.createDataFrame(data, columns)
   ```

1. Crie um banco de dados.

   ```
   spark.sql("CREATE DATABASE {} LOCATION '{}'".format(DB_NAME, TABLE_S3_LOCATION))
   ```

1. Crie uma tabela vazia do Apache Hudi.

   ```
   spark.sql("""
   CREATE TABLE {}.{} (
   language string,
   users_count int
   ) USING HUDI
   TBLPROPERTIES (
   primaryKey = 'language',
   type = 'mor'
   );
   """.format(DB_NAME, TABLE_NAME))
   ```

1. Insira uma linha de dados na tabela.

   ```
   spark.sql("""INSERT INTO {}.{} VALUES ('Golang', 3000)""".format(DB_NAME,TABLE_NAME))
   ```

1. Confirme se é possível consultar a nova tabela.

   ```
   spark.sql("SELECT * FROM {}.{}".format(DB_NAME, TABLE_NAME)).show()
   ```

# Usar tabelas do Linux Foundation Delta Lake no Amazon Athena para Apache Spark
<a name="notebooks-spark-table-formats-linux-foundation-delta-lake"></a>

O [Linux Foundation Delta Lake](https://delta.io/) é um formato de tabela que pode ser usado para análise de big data. Use o Athena para Spark para ler tabelas do Delta Lake armazenadas diretamente no Amazon S3.

Para usar tabelas do Delta Lake no Athena para Spark, configure as propriedades do Spark a seguir. Essas propriedades são configuradas por padrão no console do Athena para Spark quando você escolhe Delta Lake como formato de tabela. Para obter as etapas, consulte [Etapa 4: editar detalhes de sessões](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details) ou [Etapa 7: criar seu próprio caderno](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook).

```
"spark.sql.catalog.spark_catalog" : "org.apache.spark.sql.delta.catalog.DeltaCatalog", 
"spark.sql.extensions" : "io.delta.sql.DeltaSparkSessionExtension"
```

O procedimento a seguir mostra como usar uma tabela do Delta Lake em um caderno do Athena para Spark. Execute cada etapa em uma nova célula no caderno.

**Para usar uma tabela do Delta Lake no Athena para Spark**

1. Defina as constantes a serem usadas no caderno.

   ```
   DB_NAME = "NEW_DB_NAME" 
   TABLE_NAME = "NEW_TABLE_NAME" 
   TABLE_S3_LOCATION = "s3://amzn-s3-demo-bucket"
   ```

1. Crie um [DataFrame](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/dataframe.html) do Apache Spark.

   ```
   columns = ["language","users_count"] 
   data = [("Golang", 3000)] 
   df = spark.createDataFrame(data, columns)
   ```

1. Crie um banco de dados.

   ```
   spark.sql("CREATE DATABASE {} LOCATION '{}'".format(DB_NAME, TABLE_S3_LOCATION))
   ```

1. Crie uma tabela vazia do Delta Lake.

   ```
   spark.sql("""
   CREATE TABLE {}.{} ( 
     language string, 
     users_count int 
   ) USING DELTA 
   """.format(DB_NAME, TABLE_NAME))
   ```

1. Insira uma linha de dados na tabela.

   ```
   spark.sql("""INSERT INTO {}.{} VALUES ('Golang', 3000)""".format(DB_NAME, TABLE_NAME))
   ```

1. Confirme se é possível consultar a nova tabela.

   ```
   spark.sql("SELECT * FROM {}.{}".format(DB_NAME, TABLE_NAME)).show()
   ```

# Usar bibliotecas em Python no Athena para Spark
<a name="notebooks-spark-python-library-support"></a>

**nota**  
Esta página refere-se ao uso de bibliotecas Python na versão de lançamento do mecanismo Pyspark versão 3. A versão de lançamento do Apache Spark versão 3.5 é baseada no [Amazon EMR 7.12.](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-7120-release.html) Consulte o EMR 7.12 para ver as bibliotecas incluídas nesta versão.

Esta página descreve a terminologia usada e o gerenciamento do ciclo de vida seguido para os tempos de execução, as bibliotecas e os pacotes usados ​​no Amazon Athena para Apache Spark.

## Definições
<a name="notebooks-spark-python-library-support-definitions"></a>
+ O **Amazon Athena para Apache Spark** corresponde a uma versão personalizada do Apache Spark de código aberto. Para ver a versão atual, execute o comando `print(f'{spark.version}')` em uma célula de caderno. 
+ O **runtime do Athena** corresponde ao ambiente no qual o código é executado. O ambiente inclui um intérprete do Python e bibliotecas PySpark.
+ Uma **biblioteca ou um pacote externo** corresponde a uma biblioteca Java, Scala JAR ou Python que não faz parte do runtime do Athena, mas pode ser incluída nos trabalhos do Athena para Spark. Os pacotes externos podem ser criados por você ou pela Amazon.
+ Um **pacote de conveniência** corresponde a uma coleção de pacotes externos selecionados pelo Athena que você pode optar por incluir em suas aplicações Spark.
+ Um **pacote** combina o runtime do Athena e um pacote de conveniência.
+ Uma **biblioteca de usuário** corresponde a uma biblioteca ou a um pacote externo que você adiciona explicitamente ao seu trabalho do Athena para Spark.
  + Uma biblioteca de usuário é um pacote externo que não faz parte de um pacote de conveniência. Uma biblioteca de usuário requer carregamento e instalação, como quando você grava alguns arquivos `.py`, compacta-os e, em seguida, adiciona o arquivo `.zip` à aplicação.
+ Uma **aplicação do Athena para Spark** corresponde a um trabalho ou a uma consulta que você envia ao Athena para Spark.

## Gerenciamento de ciclo de vida
<a name="notebooks-spark-python-library-support-lifecycle-management"></a>

As seções a seguir descrevem as políticas de versionamento e obsolescência relativas a pacotes de conveniência e runtime usados no Athena para Spark.

### Versionamento e substituição do runtime
<a name="notebooks-spark-python-library-support-runtime-versioning-and-deprecation"></a>

O componente principal no runtime do Athena é o intérprete do Python. Como o Python é uma linguagem em evolução, novas versões são lançadas com regularidade e o suporte é removido para as versões mais antigas. O Athena não recomenda que você execute programas com versões obsoletas do intérprete do Python e recomenda fortemente que você use o runtime mais recente do Athena sempre que possível.

O cronograma de substituição do runtime do Athena é o seguinte:

1. Depois que o Athena fornecer um novo runtime, ele continuará a oferecer suporte ao runtime anterior por seis meses. Durante esse período, o Athena aplicará patches e atualizações de segurança ao runtime anterior.

1. Após seis meses, o Athena encerrará o suporte para o runtime anterior. O Athena não aplicará mais patches de segurança e outras atualizações ao runtime anterior. As aplicações Spark que usam o runtime anterior não serão mais elegíveis para o suporte técnico.

1. Após 12 meses, não será mais possível atualizar ou editar aplicações Spark em um grupo de trabalho que usa o runtime anterior. Recomendamos que você atualize suas aplicações Spark antes que esse período se encerre. Após o término do período, você ainda poderá executar os cadernos existentes, mas todos os cadernos que ainda usarem o runtime anterior registrarão em log um aviso nesse sentido.

1. Após 18 meses, você não poderá mais executar trabalhos no grupo de trabalho usando o runtime anterior.

### Versionamento e substituição do pacote de conveniência
<a name="notebooks-spark-python-library-support-convenience-package-versioning-and-deprecation"></a>

O conteúdo dos pacotes de conveniência é alterado ao longo do tempo. Ocasionalmente, o Athena adiciona, remove ou atualiza os pacotes de conveniência. 

O Athena usa as diretrizes a seguir para os pacotes de conveniência:
+ Os pacotes de conveniência têm um esquema de versionamento simples, como 1, 2 e 3.
+ Cada versão de pacote de conveniência inclui versões específicas de pacotes externos. Depois que o Athena cria um pacote de conveniência, o conjunto de pacotes externos do pacote de conveniência e suas versões correspondentes não são alterados.
+ O Athena cria uma nova versão de pacote de conveniência ao incluir um novo pacote externo, remover um pacote externo ou atualizar a versão de um ou mais pacotes externos.

O Athena substitui um pacote de conveniência quando substitui o runtime do Athena que o pacote usa. O Athena pode substituir os pacotes antecipadamente para limitar o número de pacotes que ele oferece suporte.

O cronograma de substituição de pacote de conveniência segue o cronograma de substituição de runtime do Athena.

# Lista de bibliotecas Python pré-instaladas
<a name="notebooks-spark-preinstalled-python-libraries"></a>

As bibliotecas Python pré-instaladas incluem o seguinte.

```
boto3==1.24.31
botocore==1.27.31
certifi==2022.6.15
charset-normalizer==2.1.0
cycler==0.11.0
cython==0.29.30
docutils==0.19
fonttools==4.34.4
idna==3.3
jmespath==1.0.1
joblib==1.1.0
kiwisolver==1.4.4
matplotlib==3.5.2
mpmath==1.2.1
numpy==1.23.1
packaging==21.3
pandas==1.4.3
patsy==0.5.2
pillow==9.2.0
plotly==5.9.0
pmdarima==1.8.5
pyathena==2.9.6
pyparsing==3.0.9
python-dateutil==2.8.2
pytz==2022.1
requests==2.28.1
s3transfer==0.6.0
scikit-learn==1.1.1
scipy==1.8.1
seaborn==0.11.2
six==1.16.0
statsmodels==0.13.2
sympy==1.10.1
tenacity==8.0.1
threadpoolctl==3.1.0
urllib3==1.26.10
pyarrow==9.0.0
```

## Observações
<a name="notebooks-spark-preinstalled-python-libraries-notes"></a>
+ Não há compatibilidade com MLLib (biblioteca de machine learning do Apache Spark) e com o pacote `pyspark.ml`.
+ No momento, `pip install` não é compatível com as sessões do Athena para Spark. 

Para obter informações sobre como importar bibliotecas Python para o Amazon Athena para Apache Spark, consulte [Importar arquivos e bibliotecas em Python para o Athena para Spark](notebooks-import-files-libraries.md).

# Importar arquivos e bibliotecas em Python para o Athena para Spark
<a name="notebooks-import-files-libraries"></a>

Este documento fornece exemplos de como importar arquivos e bibliotecas Python para o Amazon Athena para Apache Spark.

## Condições e limitações
<a name="notebooks-import-files-libraries-considerations-limitations"></a>
+ **Versão Python**: atualmente, o Athena para Spark usa o Python versão 3.9.16. Observe que os pacotes Python são sensíveis às versões secundárias do Python.
+ **Arquitetura do Athena para Spark**: o Athena para Spark usa o Amazon Linux 2 na arquitetura ARM64. Observe que algumas bibliotecas Python não distribuem binários para essa arquitetura.
+ **Objetos compartilhados binários (SOs)**: como o método [addPyFile](https://spark.apache.org/docs/latest/api/python/reference/api/pyspark.SparkContext.addPyFile.html) do SparkContext não detecta objetos binários compartilhados, ele não pode ser usado no Athena para Spark para adicionar pacotes Python que dependam de objetos compartilhados.
+ **Conjuntos de dados resilientes distribuídos (RDDs)**: [RDDs](https://spark.apache.org/docs/latest/api/python/reference/api/pyspark.RDD.html) não são compatíveis.
+ **Dataframe.foreach**: o método [DataFrame.foreach](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/api/pyspark.sql.DataFrame.foreach.html) do PySpark não é compatível.

## Exemplos
<a name="notebooks-import-files-libraries-examples"></a>

Os exemplos usam as convenções a seguir:
+ O espaço reservado para no local do Amazon S3 `s3://amzn-s3-demo-bucket`. Substitua isso pelo seu próprio local para buckets do S3.
+ Todos os blocos de código executados a partir de um shell Unix são apresentados como *directory\$1name* `$`. Por exemplo, o comando `ls` no diretório `/tmp` e sua saída são exibidos da seguinte forma:

  ```
  /tmp $ ls
  ```

  **Output**

  ```
  file1 file2
  ```

## Importar arquivos de texto para usar em cálculos
<a name="notebooks-import-files-libraries-importing-text-files"></a>

Os exemplos nesta seção mostram como importar arquivos de texto para uso em cálculos em seus cadernos no Athena para Spark.

### Adicionar um arquivo a um caderno após gravá-lo no diretório temporário local
<a name="notebooks-import-files-libraries-adding-a-file-to-a-notebook-temporary-directory"></a>

O exemplo a seguir mostra como gravar um arquivo em um diretório temporário local, adicioná-lo a um caderno e testá-lo.

```
import os
from pyspark import SparkFiles
tempdir = '/tmp/'
path = os.path.join(tempdir, "test.txt")
with open(path, "w") as testFile:
    _ = testFile.write("5")
sc.addFile(path)

def func(iterator):
    with open(SparkFiles.get("test.txt")) as testFile:
        fileVal = int(testFile.readline())
        return [x * fileVal for x in iterator]

#Test the file
from pyspark.sql.functions import udf
from pyspark.sql.functions import col

udf_with_import = udf(func)
df = spark.createDataFrame([(1, "a"), (2, "b")])
df.withColumn("col", udf_with_import(col('_2'))).show()
```

**Output**

```
Calculation completed.
+---+---+-------+
| _1| _2|    col|
+---+---+-------+
|  1|  a|[aaaaa]|
|  2|  b|[bbbbb]|
+---+---+-------+
```

### Importar um arquivo do Amazon S3
<a name="notebooks-import-files-libraries-importing-a-file-from-s3"></a>

O exemplo a seguir mostra como importar um arquivo do Amazon S3 para um caderno e testá-lo.

**Para importar um arquivo do Amazon S3 para um caderno**

1. Crie um arquivo denominado `test.txt` que tenha uma única linha com o valor `5`.

1. Adicione o arquivo a um bucket no Amazon S3. Este exemplo usa o local `s3://amzn-s3-demo-bucket`.

1. Use o código a seguir para importar o arquivo para seu caderno e realizar o teste do arquivo.

   ```
   from pyspark import SparkFiles
   sc.addFile('s3://amzn-s3-demo-bucket/test.txt')
   
   def func(iterator):
      with open(SparkFiles.get("test.txt")) as testFile:
          fileVal = int(testFile.readline())
          return [x * fileVal for x in iterator]
          
   #Test the file
   from pyspark.sql.functions import udf
   from pyspark.sql.functions import col
   
   udf_with_import = udf(func)
   df = spark.createDataFrame([(1, "a"), (2, "b")])
   df.withColumn("col", udf_with_import(col('_2'))).show()
   ```

   **Output**

   ```
   Calculation completed.
   +---+---+-------+
   | _1| _2|    col|
   +---+---+-------+
   |  1|  a|[aaaaa]|
   |  2|  b|[bbbbb]|
   +---+---+-------+
   ```

## Adicionar arquivos em Python
<a name="notebooks-import-files-libraries-adding-python-files"></a>

Os exemplos nesta seção mostram como adicionar arquivos e bibliotecas Python aos seus cadernos Spark no Athena.

### Adicionar arquivos em Python e registrar uma UDF
<a name="notebooks-import-files-libraries-adding-python-files-and-registering-a-udf"></a>

O exemplo a seguir mostra como adicionar arquivos Python do Amazon S3 ao seu caderno e registrar uma UDF.

**Para adicionar arquivos Python ao seu caderno e registrar uma UDF**

1. Usando seu próprio local do Amazon S3, crie o arquivo `s3://amzn-s3-demo-bucket/file1.py` com o seguinte conteúdo:

   ```
   def xyz(input):
       return 'xyz  - udf ' + str(input);
   ```

1. No mesmo local do S3, crie o arquivo `s3://amzn-s3-demo-bucket/file2.py` com o seguinte conteúdo:

   ```
   from file1 import xyz
   def uvw(input):
       return 'uvw -> ' + xyz(input);
   ```

1. Em seu caderno do Athena para Spark, execute os comandos a seguir.

   ```
   sc.addPyFile('s3://amzn-s3-demo-bucket/file1.py')
   sc.addPyFile('s3://amzn-s3-demo-bucket/file2.py')
   
   def func(iterator):
       from file2 import uvw
       return [uvw(x) for x in iterator]
   
   from pyspark.sql.functions import udf
   from pyspark.sql.functions import col
   
   udf_with_import = udf(func)
   
   df = spark.createDataFrame([(1, "a"), (2, "b")])
   
   df.withColumn("col", udf_with_import(col('_2'))).show(10)
   ```

   **Output**

   ```
   Calculation started (calculation_id=1ec09e01-3dec-a096-00ea-57289cdb8ce7) in (session=c8c09e00-6f20-41e5-98bd-4024913d6cee). Checking calculation status...
   Calculation completed.
   +---+---+--------------------+
   | _1| _2|                 col|
   +---+---+--------------------+
   | 1 |  a|[uvw -> xyz - ud... |
   | 2 |  b|[uvw -> xyz - ud... |
   +---+---+--------------------+
   ```

### Importar um arquivo .zip em Python
<a name="notebooks-import-files-libraries-importing-a-python-zip-file"></a>

É possível usar os métodos `addPyFile` e `import` do Python para importar um arquivo .zip do Python para o seu caderno.

**nota**  
Os arquivos `.zip` que você importa para o Athena Spark podem incluir somente pacotes Python. Por exemplo, a inclusão de pacotes com arquivos baseados em C não é compatível.

**Para importar um arquivo `.zip` do Python para seu caderno**

1. Em seu computador local, em um diretório da área de trabalho, como `\tmp`, crie um diretório denominado `moduletest`.

1. No diretório `moduletest`, crie um arquivo denominado `hello.py` com o conteúdo a seguir:

   ```
   def hi(input):
       return 'hi ' + str(input);
   ```

1. No mesmo diretório, adicione um arquivo vazio com o nome `__init__.py`.

   Se você listar o conteúdo do diretório, ele deverá se parecer com o seguinte:

   ```
   /tmp $ ls moduletest
   __init__.py       hello.py
   ```

1. Use o comando `zip` para inserir os dois arquivos do módulo em um arquivo denominado `moduletest.zip`.

   ```
   moduletest $ zip -r9 ../moduletest.zip *
   ```

1. Carregue o arquivo `.zip` em seu bucket no Amazon S3.

1. Use o código a seguir para importar o arquivo `.zip` do Python para seu caderno.

   ```
   sc.addPyFile('s3://amzn-s3-demo-bucket/moduletest.zip')
   
   from moduletest.hello import hi
   
   from pyspark.sql.functions import udf
   from pyspark.sql.functions import col
   
   hi_udf = udf(hi)
   
   df = spark.createDataFrame([(1, "a"), (2, "b")])
   
   df.withColumn("col", hi_udf(col('_2'))).show()
   ```

   **Output**

   ```
   Calculation started (calculation_id=6ec09e8c-6fe0-4547-5f1b-6b01adb2242c) in (session=dcc09e8c-3f80-9cdc-bfc5-7effa1686b76). Checking calculation status...
   Calculation completed.
   +---+---+----+
   | _1| _2| col|
   +---+---+----+
   |  1|  a|hi a|
   |  2|  b|hi b|
   +---+---+----+
   ```

### Importar duas versões de uma biblioteca em Python como módulos separados
<a name="notebooks-import-files-libraries-importing-two-library-versions"></a>

Os exemplos de código a seguir mostram como adicionar e importar duas versões diferentes de uma biblioteca Python de um local no Amazon S3 como dois módulos separados. O código adicionará cada arquivo da biblioteca do S3, realizará a importação deles e, em seguida, imprimirá a versão da biblioteca para verificar a importação.

```
sc.addPyFile('s3://amzn-s3-demo-bucket/python-third-party-libs-test/simplejson_v3_15.zip')
sc.addPyFile('s3://amzn-s3-demo-bucket/python-third-party-libs-test/simplejson_v3_17_6.zip')

import simplejson_v3_15
print(simplejson_v3_15.__version__)
```

**Output**

```
3.15.0
```

```
import simplejson_v3_17_6
print(simplejson_v3_17_6.__version__)
```

**Output**

```
3.17.6
```

### Importar um arquivo .zip em Python do PyPI
<a name="notebooks-import-files-libraries-importing-a-python-zip-file-from-a-github-project"></a>

Este exemplo usa o comando `pip` para baixar de um arquivo .zip do Python referente ao projeto [bpabel/piglatin](https://github.com/bpabel/piglatin) do [Python Package Index (PyPI)](https://pypi.org/).

**Para importar um arquivo .zip do Python do PyPI**

1. Em sua área de trabalho local, use os comandos a seguir para criar um diretório denominado `testpiglatin` e criar um ambiente virtual.

   ```
   /tmp $ mkdir testpiglatin
   /tmp $ cd testpiglatin
   testpiglatin $ virtualenv .
   ```

   **Output**

   ```
   created virtual environment CPython3.9.6.final.0-64 in 410ms
   creator CPython3Posix(dest=/private/tmp/testpiglatin, clear=False, no_vcs_ignore=False, global=False)
   seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/Users/user1/Library/Application Support/virtualenv)
   added seed packages: pip==22.0.4, setuptools==62.1.0, wheel==0.37.1
   activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator
   ```

1. Crie um subdiretório chamado `unpacked` para manter o projeto.

   ```
   testpiglatin $ mkdir unpacked
   ```

1. Use o comando `pip` para instalar o projeto no diretório `unpacked`.

   ```
   testpiglatin $ bin/pip install -t $PWD/unpacked piglatin
   ```

   **Output**

   ```
   Collecting piglatin
   Using cached piglatin-1.0.6-py2.py3-none-any.whl (3.1 kB)
   Installing collected packages: piglatin
   Successfully installed piglatin-1.0.6
   ```

1. Verifique o conteúdo do diretório.

   ```
   testpiglatin $ ls
   ```

   **Output**

   ```
   bin lib pyvenv.cfg unpacked
   ```

1. Altere para o diretório `unpacked` e exiba seu conteúdo.

   ```
   testpiglatin $ cd unpacked
   unpacked $ ls
   ```

   **Output**

   ```
   piglatin piglatin-1.0.6.dist-info
   ```

1. Use o comando `zip` para inserir o conteúdo do projeto piglatin em um arquivo denominado `library.zip`.

   ```
   unpacked $ zip -r9 ../library.zip *
   ```

   **Output**

   ```
   adding: piglatin/ (stored 0%)
   adding: piglatin/__init__.py (deflated 56%)
   adding: piglatin/__pycache__/ (stored 0%)
   adding: piglatin/__pycache__/__init__.cpython-39.pyc (deflated 31%)
   adding: piglatin-1.0.6.dist-info/ (stored 0%)
   adding: piglatin-1.0.6.dist-info/RECORD (deflated 39%)
   adding: piglatin-1.0.6.dist-info/LICENSE (deflated 41%)
   adding: piglatin-1.0.6.dist-info/WHEEL (deflated 15%)
   adding: piglatin-1.0.6.dist-info/REQUESTED (stored 0%)
   adding: piglatin-1.0.6.dist-info/INSTALLER (stored 0%)
   adding: piglatin-1.0.6.dist-info/METADATA (deflated 48%)
   ```

1. (Opcional) Use os seguintes comandos para testar a importação em nível local.

   1. Defina o caminho do Python para o local do arquivo `library.zip` e inicie o Python.

      ```
      /home $ PYTHONPATH=/tmp/testpiglatin/library.zip 
      /home $ python3
      ```

      **Output**

      ```
      Python 3.9.6 (default, Jun 29 2021, 06:20:32)
      [Clang 12.0.0 (clang-1200.0.32.29)] on darwin
      Type "help", "copyright", "credits" or "license" for more information.
      ```

   1. Importe a biblioteca e execute um comando para teste.

      ```
      >>> import piglatin
      >>> piglatin.translate('hello')
      ```

      **Output**

      ```
      'ello-hay'
      ```

1. Use comandos, como apresentado a seguir, para adicionar o arquivo `.zip` do Amazon S3, importá-lo para seu caderno no Athena e testá-lo.

   ```
   sc.addPyFile('s3://amzn-s3-demo-bucket/library.zip')
   
   import piglatin
   piglatin.translate('hello')
   
   from pyspark.sql.functions import udf
   from pyspark.sql.functions import col
   
   hi_udf = udf(piglatin.translate)
   
   df = spark.createDataFrame([(1, "hello"), (2, "world")])
   
   df.withColumn("col", hi_udf(col('_2'))).show()
   ```

   **Output**

   ```
   Calculation started (calculation_id=e2c0a06e-f45d-d96d-9b8c-ff6a58b2a525) in (session=82c0a06d-d60e-8c66-5d12-23bcd55a6457). Checking calculation status...
   Calculation completed.
   +---+-----+--------+
   | _1|   _2|     col|
   +---+-----+--------+
   |  1|hello|ello-hay|
   |  2|world|orld-way|
   +---+-----+--------+
   ```

### Importar um arquivo .zip em Python do PyPI que tem dependências
<a name="notebooks-import-files-libraries-importing-a-python-zip-file-with-dependencies"></a>

Este exemplo realiza a importação do pacote [md2gemini](https://github.com/makeworld-the-better-one/md2gemini), que converte texto em markdown para o formato de texto [Gemini](https://gemini.circumlunar.space/) do PyPI. O pacote tem as seguintes [dependências](https://libraries.io/pypi/md2gemini):

```
cjkwrap
mistune
wcwidth
```

**Para importar um arquivo .zip do Python que tem dependências**

1. Em seu computador local, use os comandos a seguir para criar um diretório denominado `testmd2gemini` e criar um ambiente virtual.

   ```
   /tmp $ mkdir testmd2gemini
   /tmp $ cd testmd2gemini
   testmd2gemini$ virtualenv .
   ```

1. Crie um subdiretório chamado `unpacked` para manter o projeto.

   ```
   testmd2gemini $ mkdir unpacked
   ```

1. Use o comando `pip` para instalar o projeto no diretório `unpacked`.

   ```
   /testmd2gemini $ bin/pip install -t $PWD/unpacked md2gemini
   ```

   **Output**

   ```
   Collecting md2gemini
     Downloading md2gemini-1.9.0-py3-none-any.whl (31 kB)
   Collecting wcwidth
     Downloading wcwidth-0.2.5-py2.py3-none-any.whl (30 kB)
   Collecting mistune<3,>=2.0.0
     Downloading mistune-2.0.2-py2.py3-none-any.whl (24 kB)
   Collecting cjkwrap
     Downloading CJKwrap-2.2-py2.py3-none-any.whl (4.3 kB)
   Installing collected packages: wcwidth, mistune, cjkwrap, md2gemini
   Successfully installed cjkwrap-2.2 md2gemini-1.9.0 mistune-2.0.2 wcwidth-0.2.5
   ...
   ```

1. Altere para o diretório `unpacked` e verifique seu conteúdo.

   ```
   testmd2gemini $ cd unpacked
   unpacked $ ls -lah
   ```

   **Output**

   ```
   total 16
   drwxr-xr-x  13 user1  wheel   416B Jun  7 18:43 .
   drwxr-xr-x   8 user1  wheel   256B Jun  7 18:44 ..
   drwxr-xr-x   9 user1  staff   288B Jun  7 18:43 CJKwrap-2.2.dist-info
   drwxr-xr-x   3 user1  staff    96B Jun  7 18:43 __pycache__
   drwxr-xr-x   3 user1  staff    96B Jun  7 18:43 bin
   -rw-r--r--   1 user1  staff   5.0K Jun  7 18:43 cjkwrap.py
   drwxr-xr-x   7 user1  staff   224B Jun  7 18:43 md2gemini
   drwxr-xr-x  10 user1  staff   320B Jun  7 18:43 md2gemini-1.9.0.dist-info
   drwxr-xr-x  12 user1  staff   384B Jun  7 18:43 mistune
   drwxr-xr-x   8 user1  staff   256B Jun  7 18:43 mistune-2.0.2.dist-info
   drwxr-xr-x  16 user1  staff   512B Jun  7 18:43 tests
   drwxr-xr-x  10 user1  staff   320B Jun  7 18:43 wcwidth
   drwxr-xr-x   9 user1  staff   288B Jun  7 18:43 wcwidth-0.2.5.dist-info
   ```

1. Use o comando `zip` para inserir o conteúdo do projeto md2gemini em um arquivo denominado `md2gemini.zip`.

   ```
   unpacked $ zip -r9 ../md2gemini *
   ```

   **Output**

   ```
     adding: CJKwrap-2.2.dist-info/ (stored 0%)
     adding: CJKwrap-2.2.dist-info/RECORD (deflated 37%)
     ....
     adding: wcwidth-0.2.5.dist-info/INSTALLER (stored 0%)
     adding: wcwidth-0.2.5.dist-info/METADATA (deflated 62%)
   ```

1. (Opcional) Use os comandos a seguir para testar se a biblioteca funciona em seu computador local.

   1. Defina o caminho do Python para o local do arquivo `md2gemini.zip` e inicie o Python.

      ```
      /home $ PYTHONPATH=/tmp/testmd2gemini/md2gemini.zip 
      /home python3
      ```

   1. Importe a biblioteca e execute um teste.

      ```
      >>> from md2gemini import md2gemini
      >>> print(md2gemini('[abc](https://abc.def)'))
      ```

      **Output**

      ```
      https://abc.def abc
      ```

1. Use os comandos a seguir para adicionar o arquivo `.zip` do Amazon S3, importá-lo para seu caderno no Athena e executar um teste que não seja UDF.

   ```
   # (non udf test)
   sc.addPyFile('s3://amzn-s3-demo-bucket/md2gemini.zip')
   from md2gemini import md2gemini
   print(md2gemini('[abc](https://abc.def)'))
   ```

   **Output**

   ```
   Calculation started (calculation_id=0ac0a082-6c3f-5a8f-eb6e-f8e9a5f9bc44) in (session=36c0a082-5338-3755-9f41-0cc954c55b35). Checking calculation status...
   Calculation completed.
   => https://abc.def (https://abc.def/) abc
   ```

1. Use os comandos a seguir para executar um teste que seja UDF.

   ```
   # (udf test)
   
   from pyspark.sql.functions import udf
   from pyspark.sql.functions import col
   from md2gemini import md2gemini
   
   
   hi_udf = udf(md2gemini)
   df = spark.createDataFrame([(1, "[first website](https://abc.def)"), (2, "[second website](https://aws.com)")])
   df.withColumn("col", hi_udf(col('_2'))).show()
   ```

   **Output**

   ```
   Calculation started (calculation_id=60c0a082-f04d-41c1-a10d-d5d365ef5157) in (session=36c0a082-5338-3755-9f41-0cc954c55b35). Checking calculation status...
   Calculation completed.
   +---+--------------------+--------------------+
   | _1|                  _2|                 col|
   +---+--------------------+--------------------+
   |  1|[first website](h...|=> https://abc.de...|
   |  2|[second website](...|=> https://aws.co...|
   +---+--------------------+--------------------+
   ```

# Usar as propriedades do Spark para especificar uma configuração personalizada
<a name="notebooks-spark-custom-jar-cfg"></a>

Ao criar ou editar uma sessão no Amazon Athena para Apache Spark, você pode usar as [propriedades do Spark](https://spark.apache.org/docs/latest/configuration.html#spark-properties) para especificar arquivos `.jar`, pacotes ou outra configuração personalizada para a sessão. Para especificar propriedades do Spark, use o console do Athena, a AWS CLI ou a API do Athena.

## Usar o console do Athena para especificar as propriedades do Spark
<a name="notebooks-spark-custom-jar-cfg-console"></a>

No console do Athena, é possível especificar as propriedades do Spark ao [criar um caderno](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook) ou [editar uma sessão atual](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details).

**Para adicionar propriedades na caixa de diálogo **Criar caderno** ou **Editar detalhes da sessão****

1. Expanda as **propriedades do Spark**.

1. Para adicionar propriedades, use a opção **Editar na tabela** ou **Editar em JSON**.
   + Para a opção **Editar na tabela**, escolha **Adicionar propriedade** para adicionar uma propriedade, ou escolha **Remover** para remover uma propriedade. Use as caixas **Chave** e **Valor** para inserir os nomes das propriedades e os respectivos valores.
     + Para adicionar um arquivo `.jar` personalizado, use a propriedade `spark.jars`.
     + Para especificar um arquivo de pacote, especifique a propriedade `spark.jars.packages`.
   + Para inserir e editar sua configuração diretamente, escolha a opção **Editar em JSON**. No editor de texto JSON, você pode executar as seguintes tarefas:
     + Escolha **Copiar** para copiar o texto JSON para a área de transferência.
     + Escolha **Limpar** para remover todo o texto do editor JSON.
     + Escolha o ícone de configurações (engrenagem) para configurar a quebra de linha ou escolha um tema de cores para o editor JSON.

### Observações
<a name="notebooks-spark-custom-jar-cfg-notes"></a>
+ É possível definir propriedades no Athena para Spark, que é o mesmo que definir as [propriedades do Spark](https://spark.apache.org/docs/latest/configuration.html#spark-properties) diretamente em um objeto [SparkConf](https://spark.apache.org/docs/latest/api/python/reference/api/pyspark.SparkConf.html).
+ Inicie todas as propriedades do Spark com o prefixo `spark.`. As propriedades com outros prefixos são ignoradas.
+ Nem todas as propriedades do Spark estão disponíveis para configuração personalizada no Athena. Se você enviar uma solicitação `StartSession` com uma configuração restrita, a sessão não será iniciada.
  + Não é possível usar o prefixo `spark.athena.` porque ele é reservado.

## Usar a AWS CLI ou a API do Athena para fornecer uma configuração personalizada
<a name="notebooks-spark-custom-jar-cfg-cli-or-api"></a>

Para usar a AWS CLI ou a API do Athena para fornecer sua configuração de sessão, use a ação de API [StartSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartSession.html) ou o comando [start-session](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/athena/start-session.html) da CLI. Em sua solicitação `StartSession`, use o campo `SparkProperties` do objeto [EngineConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EngineConfiguration.html) para passar suas informações de configuração no formato JSON. Isso iniciará uma sessão com a configuração especificada.

Para especificar propriedades personalizadas do Spark na AWS CLI, use a configuração `engine-configuration` ao iniciar uma sessão interativa.

```
aws athena start-session \ 
--region "REGION"
--work-group "WORKGROUP" \
--engine-configuration '{
    "Classifications": [{
      "Name": "spark-defaults",
      "Properties": {
        "spark.dynamicAllocation.minExecutors": "1",
        "spark.dynamicAllocation.initialExecutors": "2",
        "spark.dynamicAllocation.maxExecutors": "10",
        "spark.dynamicAllocation.executorIdleTimeout": "300"
      }
    }]
  }'
```

Você também pode especificar padrões de configuração no nível do grupo de trabalho usando a ação da API `CreateWorkgroup` ou a ação da API `UpdateWorkgroup`. Os padrões de configuração definidos no grupo de trabalho se aplicam a todas as sessões iniciadas para esse grupo de trabalho.

Para especificar as propriedades padrão do Spark na AWS CLI para um grupo de trabalho, use a configuração `engine-configuration` ao criar um novo grupo de trabalho:

```
aws athena create-work-group \
  --region "REGION" \
  --name "WORKGROUP_NAME" \
  --configuration '{
    "EngineVersion": {
      "SelectedEngineVersion": "Apache Spark version 3.5"
    },
    "ExecutionRole": "EXECUTION_ROLE",
    "EngineConfiguration": {
      "Classifications": [
        {
          "Name": "spark-defaults",
          "Properties": {
            "spark.dynamicAllocation.minExecutors": "1",
            "spark.dynamicAllocation.initialExecutors": "2",
            "spark.dynamicAllocation.maxExecutors": "10",
            "spark.dynamicAllocation.executorIdleTimeout": "300"
          }
        }
      ]
    }
  }'
```

Para modificar as propriedades padrão do Spark na AWS CLI para um grupo de trabalho, use a configuração `engine-configuration` ao atualizar um grupo de trabalho. As mudanças se aplicam às novas sessões interativas daqui em diante.

```
aws athena update-work-group \
  --region "REGION" \
  --work-group "WORKGROUP_NAME" \
  --configuration-updates '{
    "EngineVersion": {
      "SelectedEngineVersion": "Apache Spark version 3.5"
    },
    "ExecutionRole": "EXECUTION_ROLE",
    "EngineConfiguration": {
      "Classifications": [
        {
          "Name": "spark-defaults",
          "Properties": {
            "spark.dynamicAllocation.minExecutors": "1",
            "spark.dynamicAllocation.initialExecutors": "2",
            "spark.dynamicAllocation.maxExecutors": "12",
            "spark.dynamicAllocation.executorIdleTimeout": "300"
          }
        }
      ]
    }
  }'
```

# Formatos de dados e de armazenamento compatíveis
<a name="notebooks-spark-data-and-storage-formats"></a>

A tabela a seguir apresenta os formatos com suporte nativo para Apache Spark no Athena.


****  

| **Formato de dados** | **Ler** | **Escrever** | **Compressão de gravação** | 
| --- | --- | --- | --- | 
| parquet | sim | sim | nenhum, descompactado, snappy, gzip | 
| orc | sim | sim | nenhum, snappy, zlib, lzo | 
| json | sim | sim | bzip2, gzip, desinflar | 
| csv | sim | sim | bzip2, gzip, desinflar | 
| texto | sim | sim | nenhum, bzip2, gzip, desinflar | 
| arquivos binários | sim | N/D | N/D | 

# Monitorar as métricas do Apache Spark com o CloudWatch
<a name="notebooks-spark-metrics"></a>

O Athena publica métricas relacionadas a cálculos no Amazon CloudWatch quando a opção **[Publish CloudWatch metrics](notebooks-spark-getting-started.md#notebook-gs-metrics)** para seu grupo de trabalho habilitado para Spark está selecionada. É possível criar painéis personalizados, definir alarmes e acionar métricas no console do CloudWatch. 

O Athena publica a seguinte métrica no console do CloudWatch sob o namespace `AmazonAthenaForApacheSpark`:
+ `DPUCount`: a quantidade de DPUs consumidas durante a sessão para executar os cálculos.

Essa métrica tem as seguintes dimensões:
+ `SessionId`: o ID da sessão para a qual os cálculos são enviados.
+ `WorkGroup`: o nome do grupo de trabalho.

**Para visualizar as métricas para grupos de trabalho habilitados para Spark no console do Amazon CloudWatch**

1. Abra o console do CloudWatch, em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. No painel de navegação, escolha **Metrics** (Métricas), **All metrics** (Todas as métricas).

1. Selecione o namespace **AmazonAthenaForApacheSpark**.

**Para exibir métricas com a CLI**
+ Execute um destes procedimentos:
  + Para listar as métricas dos grupos de trabalho habilitados para Spark do Athena, abra uma solicitação de comando e use o comando a seguir:

    ```
    aws cloudwatch list-metrics --namespace "AmazonAthenaForApacheSpark"
    ```
  + Para listar todas as métricas disponíveis, use o comando a seguir:

    ```
    aws cloudwatch list-metrics
    ```

## Lista de métricas e dimensões do CloudWatch para cálculos do Apache Spark no Athena
<a name="notebooks-spark-metrics-metrics-table"></a>

Se você habilitou as métricas do CloudWatch em seu grupo de trabalho habilitado para Spark do Athena, o Athena enviará a métrica a seguir para o CloudWatch por grupo de trabalho. A métrica usa o namespace `AmazonAthenaForApacheSpark`.


****  

| Nome da métrica | Descrição | 
| --- | --- | 
| DPUCount  | A quantidade de DPUs (unidades de processamento de dados) consumidas durante a sessão para executar os cálculos. Uma DPU é uma medida relativa do poder de processamento que consiste em uma capacidade computacional de 4 vCPUs e 16 GB de memória. | 

Essa métrica tem as seguintes dimensões.


| Dimensão | Descrição | 
| --- | --- | 
| SessionId |  O ID da sessão para a qual os cálculos são enviados.  | 
| WorkGroup |  O nome do grupo de trabalho.  | 

## Lista de métricas e dimensões do CloudWatch para as sessões interativas do Athena Spark
<a name="notebooks-spark-metrics-interactive-sessions"></a>

Na versão de lançamento do Apache Spark versão 3.5, se você tiver habilitado as métricas do CloudWatch em seu grupo de trabalho do Athena Spark, o Athena enviará a métrica a seguir para o CloudWatch. A métrica usa o namespace `AmazonAthenaForApacheSpark`.


****  

| Name (Nome) | Descrição | 
| --- | --- | 
| DPUConsumed | O número de DPUs consumidas ativamente por consultas em um estado RUNNING em um momento específico em um grupo de trabalho. | 

Essa métrica tem as seguintes dimensões.


| Dimensão | Descrição | 
| --- | --- | 
| Conta |  O ID da conta da AWS.  | 
| WorkGroup |  O nome do grupo de trabalho.  | 

# Atribuição de custos no nível de sessão
<a name="notebooks-spark-cost-attribution"></a>

A partir da versão de lançamento do Apache Spark versão 3.5, o Athena permite monitorar os custos de cada sessão. Você pode definir tags de alocação de custos ao iniciar uma sessão, e os custos reportados de uma sessão aparecerão no Explorador de Custos ou nos relatórios de alocação de custos do Faturamento da AWS. Você também pode aplicar tags de alocação de custos no nível do grupo de trabalho, e elas serão copiadas para qualquer sessão iniciada nesse grupo de trabalho.

## Uso da atribuição de custos no nível de sessão
<a name="notebooks-spark-cost-attribution-usage"></a>

Por padrão, todas as tags de alocação de custos especificadas no nível do grupo de trabalho são copiadas para as sessões interativas iniciadas nesse grupo de trabalho.

Para não permitir que as tags sejam copiadas do grupo de trabalho ao iniciar uma sessão interativa na AWS CLI:

```
aws athena start-session \
  --region "REGION" \
  --work-group "WORKGROUP" \
  --tags '[
    {
      "Key": "tag_key",
      "Value": "tag_value"
    }
  ]' \
  --no-copy-work-group-tags
```

Para permitir que as tags sejam copiadas do grupo de trabalho ao iniciar uma sessão interativa na AWS CLI:

```
aws athena start-session \
  --region "REGION" \
  --work-group "WORKGROUP" \
  --copy-work-group-tags
```

## Condições e limitações
<a name="notebooks-spark-cost-attribution-considerations"></a>
+ As tags de sessão substituem as tags de grupo de trabalho com as mesmas chaves.

# Registro em log e monitoramento de sessões do Apache Spark
<a name="notebooks-spark-logging-monitoring"></a>

A partir da versão 3.5 do Apache Spark, você pode especificar o registro em log gerenciado, no Amazon S3 ou no CloudWatch, como suas opções de registro em log.

Com o registro em log gerenciado e o registro em log do S3, a tabela a seguir lista os locais de logs e a disponibilidade da interface do usuário que você pode esperar se escolher essas opções.


****  

| Opção | Logs de eventos | Logs de contêineres | Interfaces de usuário de aplicações | 
| --- | --- | --- | --- | 
| Registro em log gerenciado (padrão) | Armazenado no bucket gerenciado do S3 | Armazenado no bucket gerenciado do S3 | Compatível | 
| Registro em log gerenciado e bucket do S3 | Armazenado em ambos os locais | Armazenado no bucket do S3 | Compatível | 
| Bucket do Amazon S3 | Armazenado no bucket do S3 | Armazenado no bucket do S3 | Sem suporte1 | 

1 Sugerimos manter a opção de registro em log gerenciado selecionada. Caso contrário, você não poderá usar as interfaces de usuário integradas da aplicação.

## Registro em log gerenciado
<a name="notebooks-spark-logging-monitoring-managed"></a>

Por padrão, os grupos de trabalho do Athena Spark armazenam logs de aplicações com segurança em buckets gerenciados por serviços do S3 por no máximo 30 dias.

Opcionalmente, você pode fornecer uma chave do KMS (id da chave, arn, alias ou alias arn) que o serviço usará para criptografar os logs gerenciados.

```
aws athena start-session \
  --work-group "WORKGROUP" \
  --monitoring-configuration '{
    "ManagedLoggingConfiguration": {
        "Enabled": true,
        "KmsKey": "KMS_KEY"
    },
  }'
  --engine-configuration ''
```

**nota**  
Se você desativar o registro em log gerenciado, o Athena não poderá solucionar problemas de sessões em seu nome. Exemplo: você não acessará a interface do usuário do Spark nos cadernos do Estúdio Amazon SageMaker AI ou usando a API `GetResourceDashboard`.

Para desativar essa opção na AWS CLI, use a configuração `ManagedLoggingConfiguration` ao iniciar uma sessão interativa.

```
aws athena start-session \
  --work-group "WORKGROUP" \
  --monitoring-configuration '{
    "ManagedLoggingConfiguration": {
      "Enabled": false
    },
  }'
  --engine-configuration ''
```

### Permissões necessárias para registro em log gerenciado
<a name="notebooks-spark-logging-monitoring-managed-permissions"></a>

Se você forneceu uma chave do KMS, precisará das permissões a seguir na política de permissões para o perfil de execução.

```
{
    "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
    ],
    "Resource": "*",
    "Effect": "Allow"
}
```

## Registro em log do Amazon S3
<a name="notebooks-spark-logging-monitoring-s3"></a>

Você pode configurar a entrega de logs para buckets do Amazon S3.

Para habilitar a entrega de logs do S3 na AWS CLI, use a configuração `S3LoggingConfiguration` ao iniciar uma sessão interativa.

```
aws athena start-session \
  --work-group "WORKGROUP" \
  --monitoring-configuration '{
    "S3LoggingConfiguration": {
      "Enabled":true,
      "LogLocation": "s3://bucket/",
    },
  }'
  --engine-configuration ''
```

Opcionalmente, você pode fornecer uma chave do KMS (id da chave, arn, alias ou alias arn) que o serviço usará para criptografar os logs do S3.

```
aws athena start-session \
  --work-group "WORKGROUP" \
  --monitoring-configuration '{
    "S3LoggingConfiguration": {
      "Enabled":true,
      "LogLocation": "s3://bucket/",
      "KmsKey": "KMS_KEY"
    },
  }'
  --engine-configuration ''
```

### Permissões necessárias para a entrega de logs do Amazon S3
<a name="notebooks-spark-logging-monitoring-s3-permissions"></a>

Antes que suas sessões possam entregar logs aos buckets do Amazon S3, inclua as permissões na política de permissões para o perfil de execução.

```
{
    "Action": "s3:*",
    "Resource": "*",
    "Effect": "Allow"
}
```

Se você forneceu uma chave do KMS, também precisará das permissões a seguir na política de permissões para o perfil de execução.

```
{
    "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
    ],
    "Resource": "*",
    "Effect": "Allow"
}
```

Se a chave do KMS e o bucket não forem da mesma conta, o KMS precisará permitir a entidade principal do serviço do S3.

```
{
  "Effect": "Allow",
  "Principal": { "Service": "s3.amazonaws.com" },
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:GenerateDataKey*"
  ],
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "aws:SourceAccount": "ACCOUNT_HAVING_KMS_KEY"
    }
  }
}
```

## Registro em log do CloudWatch
<a name="notebooks-spark-logging-monitoring-cloudwatch"></a>

Você pode configurar a entrega de logs para grupos de logs do CloudWatch.

Para habilitar a entrega de logs do S3 na AWS CLI, use a configuração `CloudWatchLoggingConfiguration` ao iniciar uma sessão interativa.

```
aws athena start-session \
  --work-group "WORKGROUP" \
  --monitoring-configuration '{
    "CloudWatchLoggingConfiguration": {
      "Enabled": true,
      "LogGroup": "/aws/athena/sessions/${workgroup}",
      "LogStreamNamePrefix": "session-"
    }
  }'
  --engine-configuration ''
```

Todos os logs serão entregues por padrão, mas você pode, opcionalmente, especificar quais tipos de logs incluir.

```
aws athena start-session \
  --work-group "WORKGROUP" \
  --monitoring-configuration '{
    "CloudWatchLoggingConfiguration": {
      "Enabled": true,
      "LogGroup": "/aws/athena/sessions/${workgroup}",
      "LogStreamNamePrefix": "session-",
      "LogTypes": {
          "SPARK_DRIVER": [
              "STDOUT",
              "STDERR"
          ],
          "SPARK_EXECUTOR": [
              "STDOUT",
              "STDERR"
          ]
       }
    }
  }'
  --engine-configuration ''
```

### Permissões necessárias para a entrega de logs ao CloudWatch
<a name="notebooks-spark-logging-monitoring-cloudwatch-permissions"></a>

Para que suas sessões possam entregar logs aos grupos de logs do CloudWatch, inclua as permissões a seguir na política de permissões para o perfil de execução.

```
{
    "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams"
    ],
    "Resource": "*",
    "Effect": "Allow"
}
```

E a permissão a seguir na política de recursos da chave do KMS.

```
{
  "Effect": "Allow",
  "Principal": {
    "Service": "logs.<region>.amazonaws.com"
  },
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:ReEncrypt*",
    "kms:GenerateDataKey*",
    "kms:DescribeKey"
  ],
  "Resource": "*"
}
```

## Configuração de padrões de registro em log no grupo de trabalho
<a name="notebooks-spark-logging-monitoring-workgroup-defaults"></a>

Você também pode especificar as opções padrão de registro em log no nível do grupo de trabalho.

Para especificar as opções padrão de registro em log na AWS CLI para um grupo de trabalho, use a configuração `monitoring-configuration` ao criar um novo grupo de trabalho:

```
aws athena create-work-group \
  --region "REGION" \
  --name "WORKGROUP_NAME" \
  --monitoring-configuration '{
      "CloudWatchLoggingConfiguration": {
          "Enabled": true,
          "LogGroup": "/aws/athena/sessions/${workgroup}",
          "LogStreamNamePrefix": "session-",
          "LogTypes": {
              "SPARK_DRIVER": [
                  "STDOUT",
                  "STDERR"
              ],
              "SPARK_EXECUTOR": [
                  "STDOUT",
                  "STDERR"
              ]
          }
        },
        "ManagedLoggingConfiguration": {
            "Enabled": true,
            "KmsKey": "KMS_KEY"
        },
        "S3LoggingConfiguration": {
            "Enabled": true,
            "KmsKey": "KMS_KEY"
            "LogLocation": "s3://bucket/",
            "LogTypes": {
                "SPARK_DRIVER": [
                    "STDOUT",
                    "STDERR"
                ],
                "SPARK_EXECUTOR": [
                    "STDOUT",
                    "STDERR"
                ]
            }
        }
    }'
```

Para modificar as opções padrão de registro em log na AWS CLI para um grupo de trabalho, use a configuração `monitoring-configuration` ao atualizar um grupo de trabalho. As mudanças se aplicam às novas sessões interativas daqui em diante.

```
aws athena update-work-group \
  --region "REGION" \
  --work-group "WORKGROUP_NAME" 
  --monitoring-configuration '{
      "CloudWatchLoggingConfiguration": {
          "Enabled": true,
          "LogGroup": "/aws/athena/sessions/${workgroup}",
          "LogStreamNamePrefix": "session-",
          "LogTypes": {
              "SPARK_DRIVER": [
                  "STDOUT",
                  "STDERR"
              ],
              "SPARK_EXECUTOR": [
                  "STDOUT",
                  "STDERR"
              ]
          }
        },
        "ManagedLoggingConfiguration": {
            "Enabled": true,
            "KmsKey": "KMS_KEY"
        },
        "S3LoggingConfiguration": {
            "Enabled": true,
            "KmsKey": "KMS_KEY"
            "LogLocation": "s3://bucket/",
            "LogTypes": {
                "SPARK_DRIVER": [
                    "STDOUT",
                    "STDERR"
                ],
                "SPARK_EXECUTOR": [
                    "STDOUT",
                    "STDERR"
                ]
            }
        }
    }'
```

# Acesso à interface do usuário do Spark
<a name="notebooks-spark-ui-access"></a>

As interfaces do usuário do Apache Spark apresentam interfaces visuais com informações detalhadas sobre seus trabalhos em execução e concluídos do Spark. Você pode monitorar e depurar sessões interativas no Athena Spark usando interfaces do usuário nativas do Apache Spark, em que você pode se aprofundar em métricas e informações específicas do trabalho sobre cronogramas, etapas, tarefas e executores de eventos para cada trabalho do Spark.

## Acesso à interface do usuário do Spark
<a name="notebooks-spark-ui-access-methods"></a>

Depois de iniciar uma sessão interativa do Athena Spark, você pode visualizar a interface do usuário do Spark em tempo real para executar sessões nos cadernos do Estúdio Unificado Amazon SageMaker AI ou solicitar um URL seguro usando a API `GetResourceDashboard`. Nas sessões concluídas, você pode visualizar o servidor de histórico do Spark nos cadernos do Estúdio Unificado Amazon SageMaker AI, no console do Amazon Athena ou usando a mesma API.

```
aws athena get-resource-dashboard \
  --region "REGION" \
  --session-id "SESSION_ID"
```

## Permissões necessárias para acessar a interface do usuário do Spark
<a name="notebooks-spark-ui-access-permissions"></a>

Antes de acessar a interface do usuário do Spark, inclua as permissões a seguir na política de permissões do usuário ou perfil.

```
{
    "Action": "athena:GetResourceDashboard",
    "Resource": "WORKGROUP",
    "Effect": "Allow"
}
```

# Compatibilidade com o Spark Connect
<a name="notebooks-spark-connect"></a>

O Spark Connect é uma arquitetura cliente-servidor para o Apache Spark que separa o cliente da aplicação do processo de driver do cluster do Spark, permitindo conectividade remota com o Spark de clientes compatíveis. O Spark Connect também permite a depuração interativa durante o desenvolvimento diretamente de seus IDEs/clientes preferenciais.

A partir da versão de lançamento do Apache Spark versão 3.5, o Athena é compatível com o Spark Connect como um endpoint da AWS acessível usando a API `GetSessionEndpoint`.

## Exemplos de API/CLI (GetSessionEndpoint)
<a name="notebooks-spark-connect-api-examples"></a>

Você pode usar a API `GetSessionEndpoint` para obter o endpoint do Spark Connect para uma sessão interativa.

```
aws athena get-session-endpoint \
  --region "REGION" \
  --session-id "SESSION_ID"
```

Essa API retorna o URL do endpoint do Spark Connect para essa sessão.

```
{
  "EndpointUrl": "ENDPOINT_URL",
  "AuthToken": "AUTH_TOKEN",
  "AuthTokenExpirationTime": "AUTH_TOKEN_EXPIRY_TIME"
}
```

## Conectar de clientes autogerenciados
<a name="notebooks-spark-connect-self-managed"></a>

Você pode se conectar a uma sessão interativa do Athena Spark de clientes autogerenciados.

### Pré-requisitos
<a name="notebooks-spark-connect-prerequisites"></a>

Instale o cliente pyspark-connect para Spark 3.5.6 e o AWS SDK para Python.

```
pip install --user pyspark[connect]==3.5.6
pip install --user boto3
```

Confira este exemplo de script Python para enviar solicitações diretamente para um endpoint da sessão:

```
import boto3
import time
from pyspark.sql import SparkSession

client = boto3.client('athena', region_name='<REGION>')

# start the session
response = client.start_session(
    WorkGroup='<WORKGROUP_NAME>',
    EngineConfiguration={}
)

# wait for the session endpoint to be ready
time.sleep(5)
response = client.get_session_endpoint(SessionId=session_id)

# construct the authenticated remote url
authtoken=response['AuthToken']
endpoint_url=response['EndpointUrl']
endpoint_url=endpoint_url.replace("https", "sc")+":443/;use_ssl=true;"
url_with_headers = (
    f"{endpoint_url}"
    f"x-aws-proxy-auth={authtoken}"
)

# start the Spark session
start_time = time.time()
spark = SparkSession.builder\
    .remote(url_with_headers)\
    .getOrCreate()
 
spark.version 

#
# Enter your spark code here
#

# stop the Spark session
spark.stop()
```

Confira a seguir um exemplo de script Python para acessar a interface do usuário ativa ou o servidor de histórico do Spark de uma sessão:

```
Region='<REGION>'
WorkGroupName='<WORKGROUP_NAME>'
SessionId='<SESSION_ID>'
Partition='aws'
Account='<ACCOUNT_NUMBER>'

SessionARN=f"arn:{Partition}:athena:{Region}:{Account}:workgroup/{WorkGroupName}/session/{SessionId}"

# invoke the API to get the live UI/persistence UI for a session
response = client.get_resource_dashboard(
    ResourceARN=SessionARN
)
response['Url']
```

# Habilitar buckets do Amazon S3 de pagamento pelo solicitante no Athena para Spark
<a name="notebooks-spark-requester-pays"></a>

Quando um bucket do Amazon S3 é configurado como pagamento pelo solicitante, a conta do usuário que executa a consulta é cobrada pelas taxas de acesso e transferência de dados associadas à consulta. Para obter mais informações, consulte [Configuração de buckets de Pagamento pelo solicitante para transferências de armazenamento e uso](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RequesterPaysBuckets.html) no *Guia do usuário do Amazon S3*.

No Athena para Spark, os buckets de pagamentos pelo solicitante são habilitados por sessão, não por grupo de trabalho. Em um nível alto, habilitar os buckets de pagamentos pelo solicitante inclui as seguintes etapas:

1. No console do Amazon S3, habilite os pagamentos pelo solicitante nas propriedades do bucket e adicione uma política de bucket para especificar o acesso.

1. No console do IAM, crie uma política do IAM para permitir o acesso ao bucket e, em seguida, anexe a política ao perfil do IAM que será usado para acessar o bucket de pagamentos pelo solicitante.

1. No Athena para Spark, adicione uma propriedade de sessão para habilitar o recurso de pagamento pelo solicitante.

## Etapa 1: habilitar pagamento pelo solicitante em um bucket do Amazon S3 e adicionar uma política de bucket
<a name="notebooks-spark-requester-pays-enable-requester-pays-on-an-amazon-s3-bucket"></a>

**Habilitar o pagamento pelo solicitante para um bucket do Amazon S3**

1. Abra o console do Amazon S3, em [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).

1. Na lista de buckets, escolha o link do bucket para o qual você deseja habilitar o pagamento pelo solicitante.

1. Na página do bucket, escolha a aba **Propriedades**.

1. Role para baixo até a seção **Pagamentos pelo solicitante** e depois escolha **Editar**.

1. Na página **Editar pagamentos pelo solicitante**, escolha **Habilitar** e, em seguida, escolha **Salvar alterações**.

1. Escolha a aba **Permissions** (permissões).

1. Na seção **Política de bucket**, escolha **Editar**.

1. Na página **Editar política de bucket**, aplique a política de bucket que você deseja ao bucket de origem. O exemplo de política a seguir dá acesso a todas as entidades principais da AWS (`"AWS": "*"`), mas seu acesso pode ser mais granular. Por exemplo, talvez você queira especificar somente um perfil do IAM específico em outra conta.

------
#### [ JSON ]

****  

   ```
   { "Version":"2012-10-17",		 	 	  "Statement": [ { "Sid": "Statement1", "Effect": "Allow",
       "Principal": { "AWS": "arn:aws:iam::111122223333:root" },
       "Action": "s3:*", "Resource": [
           "arn:aws:s3:::111122223333-us-east-1-amzn-s3-demo-bucket",
           "arn:aws:s3:::555555555555-us-east-1-amzn-s3-demo-bucket/*"
       ] } ] }
   ```

------

## Etapa 2: criar uma política do IAM e anexá-la a um perfil do IAM
<a name="notebooks-spark-requester-pays-create-an-iam-policy-and-attach-it-to-an-iam-role"></a>

Depois, você cria uma política do IAM para permitir acesso ao bucket. Em seguida, você anexa a política ao perfil que será usado para acessar o bucket de pagamentos pelo solicitante.

**Criar uma política do IAM para o bucket de pagamentos pelo solicitante e anexá-la a um perfil**

1. Abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. No painel de navegação do console IAM, escolha **Políticas**.

1. Escolha **Create policy**.

1. Escolha **JSON**.

1. No **Editor de política**, adicione uma política como a seguinte:

------
#### [ JSON ]

****  

   ```
   { "Version":"2012-10-17",		 	 	  "Statement": [ { "Action": [ "s3:*" ], "Effect": "Allow",
       "Resource": [
           "arn:aws:s3:::111122223333-us-east-1-amzn-s3-demo-bucket",
           "arn:aws:s3:::111122223333-us-east-1-amzn-s3-demo-bucket/*"
       ] } ] }
   ```

------

1. Escolha **Next** (próximo).

1. Na página **Revisar e criar**, digite um nome e uma descrição opcional para a política e, em seguida, escolha **Criar política**.

1. No painel de navegação, escolha **Perfis**.

1. Na página **Perfis**, localize o perfil que você deseja usar e escolha o link do nome do perfil.

1. Na seção **Políticas de permissões**, escolha **Adicionar permissões**, **Anexar políticas**.

1. Na seção **Outras políticas de permissões**, selecione a caixa de seleção da política que você criou e escolha **Adicionar permissões**.

## Etapa 3: adicionar uma propriedade de sessão do Athena para Spark
<a name="notebooks-spark-requester-pays-add-a-session-property"></a>

Depois de configurar o bucket do Amazon S3 e as permissões associadas para pagamentos pelo solicitante, você pode habilitar o atributo em uma sessão do Athena para Spark.

**Habilitar buckets de pagamentos pelo solicitante em uma sessão do Athena para Spark**

1. No editor do notebook, no menu **Session** (sessão) no canto superior direito, escolha **Edit session** (editar sessão).

1. Expanda as **propriedades do Spark**. 

1. Escolha **Editar em JSON**. 

1. No editor de texto JSON, insira o seguinte:

   ```
   {
     "spark.hadoop.fs.s3.useRequesterPaysHeader":"true"
   }
   ```

1. Escolha **Salvar**.

# Uso do Lake Formation com grupos de trabalho do Athena Spark
<a name="notebooks-spark-lakeformation"></a>

Com a versão de lançamento do Apache Spark versão 3.5, você pode aproveitar o AWS Lake Formation com o Catálogo de Dados do AWS Glue, em que o perfil de execução da sessão tem permissões completas da tabela. Esse recurso permite que você leia e grave em tabelas protegidas pelo Lake Formation nas sessões interativas do Athena Spark. Consulte as seções a seguir para saber mais sobre o Lake Formation e como usá-lo com o Athena Spark.

## Etapa 1: habilitar o acesso total à tabela no Lake Formation
<a name="notebooks-spark-lakeformation-enable-fta"></a>

Para usar o modo de acesso total à tabela (FTA), você precisa permitir que o Athena Spark acesse dados sem a validação das tags de sessão do IAM no AWS Lake Formation. Para habilitar, siga as etapas em [Application integration for full table access](https://docs.aws.amazon.com//lake-formation/latest/dg/fta-app-integration.html).

### Etapa 1.1: registrar os locais de dados no Lake Formation usando o perfil definido pelo usuário
<a name="notebooks-spark-lakeformation-register-locations"></a>

Você deve usar um perfil definido pelo usuário para registrar locais de dados no AWS Lake Formation. Consulte [Requisitos para perfis usados para registrar locais](https://docs.aws.amazon.com//lake-formation/latest/dg/registration-role.html) para obter detalhes.

## Etapa 2: configurar as permissões do IAM para o perfil de execução da sessão
<a name="notebooks-spark-lakeformation-iam-permissions"></a>

Para acesso de leitura ou gravação aos dados subjacentes, além das permissões do Lake Formation, o perfil de execução precisa da permissão `lakeformation:GetDataAccess` do IAM. Com essa permissão, o Lake Formation concede a solicitação de credenciais temporárias para acessar os dados.

Confira a seguir um exemplo de política de como fornecer permissões do IAM para acesso a um script no Amazon S3, upload de logs no S3, permissões da API do AWS Glue e permissão para acessar o Lake Formation.

### Etapa 2.1: configurar as permissões do Lake Formation
<a name="notebooks-spark-lakeformation-configure-permissions"></a>
+ Os trabalhos do Spark que leem dados do S3 precisam da permissão `SELECT` do Lake Formation.
+ Os trabalhos do Spark que gravam/excluem dados no S3 precisam da permissão `ALL (SUPER)` do Lake Formation.
+ Os trabalhos do Spark que interagem com o Catálogo de Dados do AWS Glue precisam das permissões `DESCRIBE`, `ALTER` e `DROP`, conforme apropriado.

## Etapa 3: inicializar uma sessão do Spark para acesso total à tabela usando o Lake Formation
<a name="notebooks-spark-lakeformation-initialize-session"></a>

### Pré-requisitos
<a name="notebooks-spark-lakeformation-prerequisites"></a>

O Catálogo de Dados do AWS Glue deve ser configurado como um metastore para acessar as tabelas do Lake Formation.

Defina as seguintes configurações para configurar o catálogo do AWS Glue como um metastore:

```
{
  "spark.hadoop.glue.catalogid": "ACCOUNT_ID",
  "spark.hadoop.hive.metastore.client.factory.class": "com.amazonaws.glue.catalog.metastore.AWSGlueDataCatalogHiveClientFactory",
  "spark.hadoop.hive.metastore.glue.catalogid": "ACCOUNT_ID",
  "spark.sql.catalogImplementation": "hive"
}
```

Para acessar as tabelas registradas no AWS Lake Formation, é necessário definir as seguintes configurações durante a inicialização do Spark a fim de configurá-lo para usar credenciais do AWS Lake Formation.

### Hive
<a name="notebooks-spark-lakeformation-hive-config"></a>

```
{
  "spark.hadoop.fs.s3.credentialsResolverClass": "com.amazonaws.glue.accesscontrol.AWSLakeFormationCredentialResolver",
  "spark.hadoop.fs.s3.useDirectoryHeaderAsFolderObject": "true",
  "spark.hadoop.fs.s3.folderObject.autoAction.disabled": "true",
  "spark.sql.catalog.skipLocationValidationOnCreateTable.enabled": "true",
  "spark.sql.catalog.createDirectoryAfterTable.enabled": "true",
  "spark.sql.catalog.dropDirectoryBeforeTable.enabled": "true"
}
```

### Apache Iceberg
<a name="notebooks-spark-lakeformation-iceberg-config"></a>

```
{
  "spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
  "spark.sql.catalog.spark_catalog": "org.apache.iceberg.spark.SparkSessionCatalog",
  "spark.sql.catalog.spark_catalog.warehouse": "s3://your-bucket/warehouse/",
  "spark.sql.catalog.spark_catalog.client.region": "REGION",
  "spark.sql.catalog.spark_catalog.catalog-impl": "org.apache.iceberg.aws.glue.GlueCatalog",
  "spark.sql.catalog.spark_catalog.glue.account-id": "ACCOUNT_ID",
  "spark.sql.catalog.spark_catalog.glue.lakeformation-enabled": "true"
}
```

### Tabelas do Amazon S3
<a name="notebooks-spark-lakeformation-s3tables-config"></a>

```
{
  "spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
  "spark.sql.catalog.{catalogName}": "org.apache.iceberg.spark.SparkCatalog",
  "spark.sql.catalog.{catalogName}.warehouse": "arn:aws:s3tables:{region}:{accountId}:bucket/{bucketName}",
  "spark.sql.catalog.{catalogName}.catalog-impl": "org.apache.iceberg.aws.glue.GlueCatalog",
  "spark.sql.catalog.{catalogName}.glue.id": "{accountId}:s3tablescatalog/{bucketName}",
  "spark.sql.catalog.{catalogName}.glue.lakeformation-enabled": "true",
  "spark.sql.catalog.{catalogName}.client.region": "REGION",
  "spark.sql.catalog.{catalogName}.glue.account-id": "ACCOUNT_ID"
}
```

### Delta Lake
<a name="notebooks-spark-lakeformation-deltalake-config"></a>

```
{
  "spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
  "spark.sql.catalog.spark_catalog": "org.apache.spark.sql.delta.catalog.DeltaCatalog",
  "spark.hadoop.fs.s3.credentialsResolverClass": "com.amazonaws.glue.accesscontrol.AWSLakeFormationCredentialResolver",
  "spark.hadoop.fs.s3.useDirectoryHeaderAsFolderObject": "true",
  "spark.hadoop.fs.s3.folderObject.autoAction.disabled": "true",
  "spark.sql.catalog.skipLocationValidationOnCreateTable.enabled": "true",
  "spark.sql.catalog.createDirectoryAfterTable.enabled": "true",
  "spark.sql.catalog.dropDirectoryBeforeTable.enabled": "true"
}
```

## Condições e limitações
<a name="notebooks-spark-lakeformation-considerations"></a>
+ O acesso total à tabela é compatível com as Tabelas do Amazon S3, Hive, Iceberg e Delta. As tabelas Hudi não oferecem suporte acesso total à tabela.
+ Para adicionar novos catálogos a uma sessão ativa, use `spark.conf.set` com novas configurações de catálogo.
+ As configurações do catálogo são imutáveis. Se você quiser atualizar uma configuração de catálogo, crie um novo catálogo usando `spark.conf.set`.
+ Adicione somente os catálogos necessários à sessão do Spark.
+ Para alterar o catálogo padrão: `spark.catalog.setCurrentCatalog("s3tablesbucket")`
+ Se você tiver caracteres especiais no nome do seu catálogo, como `-`, escape-os em sua consulta desta forma:

  ```
  SELECT sales_amount as nums FROM `my-s3-tables-bucket`.`s3namespace`.`daily_sales` LIMIT 100
  ```

# Habilitar a criptografia do Apache Spark
<a name="notebooks-spark-encryption"></a>

Você pode habilitar a criptografia do Apache Spark no Athena. Essa ação criptografa dados em trânsito entre nós do Spark e criptografa dados em repouso armazenados localmente pelo Spark. Para aumentar a segurança desses dados, o Athena usa esta configuração de criptografia:

```
spark.io.encryption.keySizeBits="256" 
spark.io.encryption.keygen.algorithm="HmacSHA384"
```

Para habilitar a criptografia do Spark, você pode usar o console do  Athena, a AWS CLI ou a API do Athena.

## Usar o console do Athena para habilitar a criptografia do Spark em um novo caderno
<a name="notebooks-spark-encryption-athena-console-new-notebook"></a>

**Para criar um novo caderno que tenha a criptografia do Spark habilitada**

1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home).

1. Se o painel de navegação do console não estiver visível, escolha o menu de expansão à esquerda.

1. Execute um destes procedimentos:
   + No **Notebook explorer** (Explorador de cadernos), escolha **Create notebook** (Criar caderno).
   + No **Notebook editor** (Editor de cadernos), escolha **Create notebook** (Criar caderno) ou selecione o ícone de adição (**\$1**) para adicionar um caderno.

1. Em **Nome do caderno**, insira um nome para o caderno.

1. Expanda a opção **Propriedades do Spark**.

1. Selecione **Ativar a criptografia do Spark**.

1. Escolha **Criar**.

A sessão do caderno que você cria é criptografada. Use o novo caderno como faria normalmente. Futuramente, quando você iniciar novas sessões que usarem o caderno, as novas sessões também serão criptografadas.

## Usar o console do Athena para habilitar a criptografia do Spark para um caderno existente
<a name="notebooks-spark-encryption-athena-console-existing-notebook"></a>

Você também pode usar o console do Athena para ativar a criptografia do Spark para um caderno existente.

**Para habilitar a criptografia para um caderno existente**

1. [Abra uma nova sessão](notebooks-spark-managing.md#opening-a-previously-created-notebook) para um caderno criado anteriormente.

1. No editor do notebook, no menu **Session** (sessão) no canto superior direito, escolha **Edit session** (editar sessão).

1. Na caixa de diálogo **Editar detalhes da sessão**, expanda **Propriedades do Spark**.

1. Selecione **Ativar a criptografia do Spark**.

1. Escolha **Salvar**.

O console inicia uma nova sessão que tem a criptografia habilitada. As sessões posteriores que você criar para o caderno também terão a criptografia habilitada.

## Usar a AWS CLI para habilitar a criptografia do Spark
<a name="notebooks-spark-encryption-cli"></a>

Você pode usar a AWS CLI para habilitar a criptografia ao iniciar uma sessão especificando as propriedades corretas do Spark.

**Para usar a AWS CLI para habilitar a criptografia do Spark**

1. Use um comando como o exemplo a seguir para criar um objeto JSON de configuração do mecanismo que especifique as propriedades de criptografia do Spark.

   ```
   ENGINE_CONFIGURATION_JSON=$( 
     cat <<EOF 
   { 
       "CoordinatorDpuSize": 1, 
       "MaxConcurrentDpus": 20, 
       "DefaultExecutorDpuSize": 1, 
       "SparkProperties": { 
         "spark.authenticate": "true", 
         "spark.io.encryption.enabled": "true", 
         "spark.network.crypto.enabled": "true" 
       } 
   } 
   EOF 
   )
   ```

1. Na AWS CLI, use o comando `athena start-session` e passe o objeto JSON que você criou para o argumento `--engine-configuration`, como no seguinte exemplo:

   ```
   aws athena start-session \ 
      --region "region" \ 
      --work-group "your-work-group" \ 
      --engine-configuration "$ENGINE_CONFIGURATION_JSON"
   ```

## Usar a API do Athena para habilitar a criptografia do Spark
<a name="notebooks-spark-encryption-api"></a>

Para habilitar a criptografia do Spark com a API do Athena, use a ação [StartSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartSession.html) e o respectivo parâmetro [EngineConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EngineConfiguration.html) de `SparkProperties` para especificar a configuração de criptografia na solicitação `StartSession`.

# Configurar o acesso entre contas do AWS Glue no Athena para Spark
<a name="spark-notebooks-cross-account-glue"></a>

Este tópico mostra como a conta do consumidor *666666666666* e a conta do proprietário *999999999999* podem ser configuradas para acesso entre contas do AWS Glue. Quando as contas são configuradas, a conta do consumidor pode executar consultas do Athena para Spark nos bancos de dados e tabelas do AWS Glue do proprietário.

## Etapa 1: fornecer acesso aos perfis de consumidor no AWS Glue
<a name="spark-notebooks-cross-account-glue-in-aws-glue-provide-access-to-the-consumer-account"></a>

No AWS Glue, o proprietário cria uma política que fornece aos perfis do consumidor acesso ao catálogo de dados do AWS Glue do proprietário.

**Adicionar uma política do AWS Glue que permita que um perfil de consumidor acesse o catálogo de dados do proprietário**

1. Usando a conta do proprietário do catálogo, faça login no Console de gerenciamento da AWS.

1. Abra o console do AWS Glue em [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/).

1. No painel de navegação, expanda **Data Catalog** e escolha **Configurações do catálogo**.

1. Na página **Configurações do catálogo de dados**, na seção **Permissões**, adicione uma política como a seguir. Essa política fornece perfis para a conta do consumidor *666666666666* acessar o catálogo de dados na conta do proprietário *999999999999*.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Sid": "Cataloguers",
               "Effect": "Allow",
               "Principal": {
                   "AWS": [
                       "arn:aws:iam::666666666666:role/Admin",
                       "arn:aws:iam::666666666666:role/AWSAthenaSparkExecutionRole"
                   ]
               },
               "Action": "glue:*",
               "Resource": [
                   "arn:aws:glue:us-west-2:999999999999:catalog",
                   "arn:aws:glue:us-west-2:999999999999:database/*",
                   "arn:aws:glue:us-west-2:999999999999:table/*"
               ]
           }
       ]
   }
   ```

------

## Etapa 2: configurar a conta de consumidor para acesso
<a name="spark-notebooks-cross-account-glue-configure-the-consumer-account-for-access"></a>

Na conta do consumidor, crie uma política para permitir o acesso ao AWS Glue Data Catalog, aos bancos de dados e às tabelas do proprietário e anexe a política a um perfil. O exemplo a seguir usa a conta de consumidor *666666666666*.

**Criar uma política do AWS Glue para acesso ao AWS Glue Data Catalog do proprietário**

1. Usando a conta do consumidor, faça login no Console de gerenciamento da AWS.

1. Abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. No painel de navegação, expanda **Gerenciamento de acesso** e escolha **Políticas**.

1. Escolha **Criar política**.

1. Na página **Especificar permissões**, escolha **JSON**.

1. No **Editor de políticas**, insira uma instrução JSON como a seguir que permite ações do AWS Glue no catálogo de dados da conta do proprietário.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "glue:*",
               "Resource": [
                   "arn:aws:glue:us-east-1:999999999999:catalog",
                   "arn:aws:glue:us-east-1:999999999999:database/*",
                   "arn:aws:glue:us-east-1:999999999999:table/*"
               ]
           }
       ]
   }
   ```

------

1. Escolha **Próximo**.

1. Na página **Revisar e criar**, para **Nome da política**, insira um nome para a política.

1. Escolha **Criar política**.

Em seguida, você usa o console do IAM na conta do consumidor para anexar a política que você acabou de criar ao perfil ou aos perfis do IAM que a conta do consumidor usará para acessar o catálogo de dados do proprietário.

**Anexar a política do AWS Glue  aos perfis na conta do consumidor**

1. No painel de navegação do console do IAM da conta do consumidor, escolha **Perfis**.

1. Na página **Perfis**, encontre o perfil ao qual você deseja anexar a política.

1. Escolha **Adicionar permissões** e depois **Anexar políticas**.

1. Encontre a política que você acabou de criar.

1. Marque a caixa de seleção da política e escolha **Adicionar permissões**.

1. Repita as etapas para adicionar a política a outros perfis que você deseja usar.

## Etapa 3: configurar uma sessão e criar uma consulta
<a name="spark-notebooks-cross-account-glue-configure-a-session-and-create-a-query"></a>

No Athena Spark, na conta do solicitante, usando o perfil especificado, crie uma sessão para testar o acesso [criando um caderno](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook) ou [editando uma sessão atual](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details). Ao [configurar as propriedades da sessão](notebooks-spark-custom-jar-cfg.md#notebooks-spark-custom-jar-cfg-console), especifique uma das seguintes opções:
+ **O separador de catálogo do AWS Glue**: com essa abordagem, você inclui o ID da conta do proprietário em suas consultas. Use esse método se você for usar a sessão para consultar catálogos de dados de diferentes proprietários.
+ **O ID do catálogo do AWS Glue**: com essa abordagem, você consulta o banco de dados diretamente. Esse método será mais conveniente se você for usar a sessão para consultar o catálogo de dados de somente um proprietário.

### Usar o separador do catálogo do AWS Glue
<a name="spark-notebooks-cross-account-glue-using-the-glue-catalog-separator-approach"></a>

Ao editar as propriedades da sessão, adicione o seguinte:

```
{ 
    "spark.hadoop.aws.glue.catalog.separator": "/" 
}
```

Ao executar uma consulta em uma célula, use uma sintaxe como a do exemplo a seguir. Observe que na cláusula `FROM`, o separador e o ID do catálogo e são necessários antes do nome do banco de dados.

```
df = spark.sql('SELECT requestip, uri, method, status FROM `999999999999/mydatabase`.cloudfront_logs LIMIT 5') 
df.show()
```

### Usar o ID do catálogo do AWS Glue
<a name="spark-notebooks-cross-account-glue-using-the-glue-catalog-id-approach"></a>

Ao editar as propriedades da sessão, insira a propriedade a seguir. Substitua *999999999999* pelo ID da conta do proprietário.

```
{ 
    "spark.hadoop.hive.metastore.glue.catalogid": "999999999999" 
}
```

Ao executar uma consulta em uma célula, use uma sintaxe como a seguir. Observe que na cláusula `FROM`, o separador e ID do catálogo não são necessários antes do nome do banco de dados.

```
df = spark.sql('SELECT * FROM mydatabase.cloudfront_logs LIMIT 10') 
df.show()
```

## Recursos adicionais
<a name="spark-notebooks-cross-account-glue-additional-resources"></a>

[Configurar o acesso entre contas aos catálogos de dados do AWS Glue](security-iam-cross-account-glue-catalog-access.md)

[Managing cross-account permissions using both AWS Glue and Lake Formation](https://docs.aws.amazon.com/lake-formation/latest/dg/hybrid-cross-account.html) no *Guia do desenvolvedor do AWS Lake Formation*.

[Configure o acesso entre contas para um AWS Glue Data Catalog compartilhado usando o Amazon Athena](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/configure-cross-account-access-to-a-shared-aws-glue-data-catalog-using-amazon-athena.html) nos *Padrões de orientação prescritiva da AWS*.

# Entender as cotas de serviço do Athena para Spark
<a name="notebooks-spark-quotas"></a>

As *service quotas*, também conhecidas como *limites*, correspondem ao número máximo de recursos ou operações de serviço que sua Conta da AWS pode usar. Para obter mais informações sobre as cotas de serviço para outros serviços AWS que você pode usar com o Amazon Athena para Spark, consulte [Cotas de serviço AWS](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html) no *Referência geral da Amazon Web Services*.

**nota**  
Os valores padrão são as cotas iniciais definidas pela AWS, as quais são separados do valor real da cota aplicada e da Service Quotas máxima possível. Novas Contas da AWS podem ter cotas iniciais mais baixas que podem ser aumentadas no decorrer do tempo. O Amazon Athena para Apache Spark monitora constantemente o uso em cada Região da AWS e aumenta automaticamente as cotas com base no uso. Se seus requisitos excederem os limites estabelecidos, entre em contato com o suporte ao cliente.

A tabela a seguir lista as cotas de serviço do Amazon Athena para o Apache Spark.


****  

| Nome | Padrão | Ajustável | Versão | Descrição | 
| --- | --- | --- | --- | --- | 
| Concorrência de DPU do Apache Spark | 160 | Não | PySpark Versão 3 | O número máximo de unidades de processamento de dados (DPUs) que você pode consumir simultaneamente para cálculos do Apache Spark para uma única conta na Região da AWS atual. Uma DPU é uma medida relativa do poder de processamento que consiste em uma capacidade computacional de 4 vCPUs e 16 GB de memória. | 
| Simultaneidade de DPU da sessão Apache Spark | 60 | Não | PySpark Versão 3 | O número máximo de DPUs que você pode consumir simultaneamente para um cálculo do Apache Spark em uma sessão. | 
| DPUs sob demanda | 4 | Não | Versão 3.5 do Apache Spark | O número máximo de unidades de processamento de dados (DPUs) que você pode consumir simultaneamente nas seções interativas do Apache Spark na Região da AWS atual. | 

# Usar APIs do Athena Spark
<a name="notebooks-spark-api-list"></a>

**nota**  
As APIs de cálculos e os cadernos do Athena estão disponíveis na versão de lançamento do mecanismo Pyspark versão 3. As APIs de cálculos e os cadernos não são compatíveis com a versão de lançamento do Apache Spark versão 3.5.

A lista a seguir contém links de referência para as ações de API disponíveis para cadernos do Athena. Para obter estruturas de dados e outras ações de API do Athena, consulte [https://docs.aws.amazon.com/athena/latest/APIReference/](https://docs.aws.amazon.com/athena/latest/APIReference/) (Referência para APIs do Amazon Athena). 
+  [CreateNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreateNotebook.html) 
+  [CreatePresignedNotebookUrl](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreatePresignedNotebookUrl.html) 
+  [DeleteNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_DeleteNotebook.html) 
+  [ExportNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_ExportNotebook.html) 
+  [GetCalculationExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetCalculationExecution.html) 
+  [GetCalculationExecutionCode](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetCalculationExecutionCode.html) 
+  [GetCalculationExecutionStatus](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetCalculationExecutionStatus.html) 
+  [GetNotebookMetadata](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetNotebookMetadata.html) 
+  [GetSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetSession.html) 
+  [GetSessionStatus](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetSessionStatus.html) 
+  [ImportNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_ImportNotebook.html) 
+  [ListApplicationDPUSizes](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListApplicationDPUSizes.html) 
+  [ListCalculationExecutions](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListCalculationExecutions.html) 
+  [ListExecutors](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListExecutors.html) 
+  [ListNotebookMetadata](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListNotebookMetadata.html) 
+  [ListNotebookSessions](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListNotebookSessions.html) 
+  [ListSessions](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListSessions.html) 
+  [StartCalculationExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartCalculationExecution.html) 
+  [StartSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartSession.html) 
+  [StopCalculationExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StopCalculationExecution.html) 
+  [TerminateSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_TerminateSession.html) 
+  [UpdateNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_UpdateNotebook.html) 
+  [UpdateNotebookMetadata](https://docs.aws.amazon.com/athena/latest/APIReference/API_UpdateNotebookMetadata.html) 

# Solucionar problemas do Athena para Spark
<a name="notebooks-spark-troubleshooting"></a>

Use as informações a seguir para solucionar problemas que você pode ter ao usar cadernos e sessões no Athena.

**Topics**
+ [Saber mais sobre os problemas conhecidos do Athena para Spark](notebooks-spark-known-issues.md)
+ [Solucionar problemas de grupos de trabalho habilitados para Spark](notebooks-spark-troubleshooting-workgroups.md)
+ [Usar a instrução EXPLAIN do Spark para solucionar problemas do Spark SQL](notebooks-spark-troubleshooting-explain.md)
+ [Registrar em log eventos de aplicação do Spark no Athena](notebooks-spark-logging.md)
+ [Use o CloudTrail para solucionar problemas de chamadas de API de cadernos do Athena](notebooks-spark-troubleshooting-cloudtrail.md)
+ [Superar o limite de tamanho de bloco de código de 68 mil](notebooks-spark-troubleshooting-code-block-size-limit.md)
+ [Solucionar erros de sessão](notebooks-spark-troubleshooting-sessions.md)
+ [Solucionar erros de tabela](notebooks-spark-troubleshooting-tables.md)
+ [Obter suporte](notebooks-spark-troubleshooting-support.md)

# Saber mais sobre os problemas conhecidos do Athena para Spark
<a name="notebooks-spark-known-issues"></a>

Essa página documenta alguns dos problemas conhecidos no Athena para Apache Spark.

## Exceção para argumento inválido ao criar uma tabela
<a name="notebooks-spark-known-issues-illegal-argument-exception"></a>

Embora o Spark não permita que bancos de dados sejam criados com uma propriedade de local vazia, os bancos de dados no AWS Glue podem ter uma propriedade `LOCATION` vazia se forem criados de forma externa ao Spark.

Se você criar uma tabela e especificar um banco de dados do AWS Glue com um campo `LOCATION` vazio, poderá ocorrer uma exceção como a seguinte: IllegalArgumentException: Cannot create a path from an empty string. (IllegalArgumentException: não é possível criar um caminho usando uma string vazia).

Por exemplo, o comando a seguir gera uma exceção se o banco de dados padrão no AWS Glue contiver um campo `LOCATION` vazio:

```
spark.sql("create table testTable (firstName STRING)")
```

**Solução sugerida A**: use o AWS Glue para adicionar um local ao banco de dados que você está usando.

**Para adicionar um local a um banco de dados 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. No painel de navegação, escolha **Bancos de dados**.

1. Na lista de bancos de dados, selecione o banco de dados que deseja editar.

1. Na página de detalhes do banco de dados, escolha **Edit** (Editar).

1. Na página **Update a database** (Atualizar um banco de dados), em **Location** (Local), insira um local do Amazon S3.

1. Escolha **Update Database** (Atualizar banco de dados).

**Solução sugerida B**: use um banco de dados diferente do AWS Glue que tenha um local válido e existente no Amazon S3. Por exemplo, se você tiver um banco de dados denominado `dbWithLocation`, use o comando `spark.sql("use dbWithLocation")` para alternar para esse banco de dados.

**Solução sugerida C**: ao usar o Spark SQL para criar a tabela, especifique um valor para `location`, como no exemplo a seguir.

```
spark.sql("create table testTable (firstName STRING) 
       location 's3://amzn-s3-demo-bucket/'").
```

**Solução sugerida D**: se você especificou um local ao criar a tabela, mas o problema persistir, certifique-se de que o caminho do Amazon S3 fornecido tenha uma barra no final. Por exemplo, o comando a seguir gera uma exceção para o argumento inválido:

```
spark.sql("create table testTable (firstName STRING) 
       location 's3://amzn-s3-demo-bucket'")
```

Para corrigir isso, adicione uma barra no final para o local (por exemplo, `'s3://amzn-s3-demo-bucket/'`).

## Banco de dados criado em um local do grupo de trabalho
<a name="notebooks-spark-known-issues-database-created-in-a-workgroup-location"></a>

Se você usar um comando como `spark.sql('create database db')` para criar um banco de dados e não especificar um local para ele, o Athena criará um subdiretório no local do seu grupo de trabalho e usará esse local para o banco de dados recém-criado.

## Problemas com tabelas gerenciadas pelo Hive no banco de dados do AWS Glue padrão
<a name="notebooks-spark-known-issues-managed-tables"></a>

Se a propriedade `Location` de seu banco de dados padrão no AWS Glue não estiver vazia e especificar um local válido no Amazon S3, e você usar o Athena para Spark para criar uma tabela gerenciada pelo Hive em seu banco de dados do AWS Glue padrão, os dados serão gravados no local do Amazon S3 especificado no grupo de trabalho do Athena Spark, e não no local especificado pelo banco de dados do AWS Glue.

Esse problema ocorre devido à forma como o Apache Hive manipula o banco de dados padrão. O Apache Hive cria dados de tabela na localização raiz do warehouse Hive, que pode ser diferente da localização real do banco de dados padrão.

Quando você usa o Athena para Spark para criar uma tabela gerenciada pelo Hive no banco de dados padrão no AWS Glue, os metadados da tabela do AWS Glue podem apontar para dois locais diferentes. Isso pode causar um comportamento inesperado ao tentar uma operação `INSERT` ou `DROP TABLE`.

Estão são as etapas para reproduzir o problema:

1. No Athena para Spark, você usa um dos seguintes métodos para criar ou salvar uma tabela gerenciada pelo Hive:
   + Uma instrução SQL como `CREATE TABLE $tableName`
   + Um comando PySpark como `df.write.mode("overwrite").saveAsTable($tableName)` que não especifica a opção `path` na API Dataframe.

   Nesse momento, o console do AWS Glue pode mostrar uma localização incorreta no Amazon S3 para a tabela.

1. No Athena para Spark, use a instrução `DROP TABLE $table_name` para eliminar a tabela que você criou.

1. Após executar a instrução `DROP TABLE`, você percebe que os arquivos subjacentes no Amazon S3 ainda estão presentes.

Para resolver esse problema, execute um dos seguintes procedimentos:

**Solução A**: use um banco de dados do AWS Glue diferente ao criar tabelas gerenciadas pelo Hive.

**Solução B**: especifique um local vazio para o banco de dados padrão no AWS Glue. Em seguida, crie as tabelas gerenciadas no banco de dados padrão.

## Incompatibilidade de formatos de arquivo CSV e JSON entre o Athena para Spark e o Athena SQL
<a name="notebooks-spark-known-issues-csv-and-json-file-format-incompatibility"></a>

Devido a um problema conhecido com o Spark de código aberto, ao criar uma tabela no Athena para Spark em dados CSV ou JSON, a tabela pode não ser legível no Athena SQL e vice-versa. 

Por exemplo, é possível criar uma tabela no Athena para Spark das seguintes maneiras: 
+ Com esta seguinte sintaxe `USING csv`: 

  ```
  spark.sql('''CREATE EXTERNAL TABLE $tableName ( 
  $colName1 $colType1, 
  $colName2 $colType2, 
  $colName3 $colType3) 
  USING csv 
  PARTITIONED BY ($colName1) 
  LOCATION $s3_location''')
  ```
+  Com a seguinte sintaxe da API [DataFrame](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/dataframe.html): 

  ```
  df.write.format('csv').saveAsTable($table_name)
  ```

Devido ao problema conhecido com o Spark de código aberto, as consultas do Athena SQL nas tabelas resultantes podem não ser bem-sucedidas. 

**Solução sugerida**: tente criar a tabela no Athena para Spark usando a sintaxe do Apache Hive. Para obter mais informações, consulte [CREATE HIVEFORMAT TABLE](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-create-table-hiveformat.html) na documentação do Apache Spark. 

# Solucionar problemas de grupos de trabalho habilitados para Spark
<a name="notebooks-spark-troubleshooting-workgroups"></a>

Use as informações apresentadas a seguir para solucionar problemas de grupos de trabalho habilitados para Spark no Athena.

## Sessão deixa de responder ao usar um perfil do IAM existente
<a name="notebooks-spark-troubleshooting-workgroups-existing-role"></a>

Se você não criou um novo `AWSAthenaSparkExecutionRole` para o grupo de trabalho habilitado para Spark e, em vez disso, atualizou ou escolheu um perfil do IAM existente, sua sessão pode deixar de responder. Nesse caso, pode ser necessário adicionar as seguintes políticas de confiança e permissões ao perfil de execução do grupo de trabalho habilitado para Spark.

Adicione a política de confiança exemplificada a seguir. A política inclui uma verificação adjunta confundida para o perfil de execução. Substitua os valores de `111122223333`, `aws-region` e `workgroup-name` pelo ID da Conta da AWS, pela Região da AWS e pelo grupo de trabalho que você está usando.

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "athena.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "111122223333"
                },
                "ArnLike": {
                    "aws:SourceArn": "arn:aws:athena:us-east-1:111122223333:workgroup/workgroup-name"
                }
            }
        }
    ]
}
```

------

Adicione uma política de permissões como a política padrão a seguir para os grupos de trabalho habilitados para cadernos. Modifique os locais reservados do Amazon S3 e os IDs da Conta da AWS para corresponder aos que você está usando. Substitua os valores de `amzn-s3-demo-bucket`, `aws-region`, `111122223333` e `workgroup-name` pelo bucket do Amazon S3, pela Região da AWS, pelo ID da Conta da AWS e pelo grupo de trabalho que você está usando.

------
#### [ JSON ]

****  

```
{ "Version":"2012-10-17",		 	 	  "Statement": [ { "Effect": "Allow", "Action": [
    "s3:PutObject", "s3:ListBucket", "s3:DeleteObject", "s3:GetObject" ], "Resource": [
        "arn:aws:s3:::amzn-s3-demo-bucket/*",
        "arn:aws:s3:::amzn-s3-demo-bucket" ] }, { "Effect": "Allow",
    "Action": [ "athena:GetWorkGroup", "athena:CreatePresignedNotebookUrl",
    "athena:TerminateSession", "athena:GetSession", "athena:GetSessionStatus",
    "athena:ListSessions", "athena:StartCalculationExecution", "athena:GetCalculationExecutionCode",
    "athena:StopCalculationExecution", "athena:ListCalculationExecutions",
    "athena:GetCalculationExecution", "athena:GetCalculationExecutionStatus",
    "athena:ListExecutors", "athena:ExportNotebook", "athena:UpdateNotebook" ], "Resource":
            "arn:aws:athena:us-east-1:111122223333:workgroup/workgroup-name"
    }, { "Effect": "Allow", "Action": [ "logs:CreateLogStream", "logs:DescribeLogStreams",
    "logs:CreateLogGroup", "logs:PutLogEvents" ], "Resource": [
            "arn:aws:logs:us-east-1:111122223333:log-group:/aws-athena:*",
            "arn:aws:logs:us-east-1:111122223333:log-group:/aws-athena*:log-stream:*"
    ] }, { "Effect": "Allow", "Action": "logs:DescribeLogGroups", "Resource":
            "arn:aws:logs:us-east-1:111122223333:log-group:*"
    }, { "Effect": "Allow", "Action": [ "cloudwatch:PutMetricData" ], "Resource": "*", "Condition":
    { "StringEquals": { "cloudwatch:namespace": "AmazonAthenaForApacheSpark" } } } ] }
```

------

# Usar a instrução EXPLAIN do Spark para solucionar problemas do Spark SQL
<a name="notebooks-spark-troubleshooting-explain"></a>

É possível usar a instrução `EXPLAIN` do Spark com o Spark SQL para solucionar problemas relacionados ao código Spark. Os exemplos de código e de saída a seguir apresentam esse uso.

**Example : instrução SELECT do Spark**  

```
spark.sql("select * from select_taxi_table").explain(True)
```
**Output**  

```
Calculation started (calculation_id=20c1ebd0-1ccf-ef14-db35-7c1844876a7e) in 
(session=24c1ebcb-57a8-861e-1023-736f5ae55386). 
Checking calculation status...

Calculation completed.
== Parsed Logical Plan ==
'Project [*]
+- 'UnresolvedRelation [select_taxi_table], [], false

== Analyzed Logical Plan ==
VendorID: bigint, passenger_count: bigint, count: bigint
Project [VendorID#202L, passenger_count#203L, count#204L]
+- SubqueryAlias spark_catalog.spark_demo_database.select_taxi_table
   +- Relation spark_demo_database.select_taxi_table[VendorID#202L,
       passenger_count#203L,count#204L] csv

== Optimized Logical Plan ==
Relation spark_demo_database.select_taxi_table[VendorID#202L,
passenger_count#203L,count#204L] csv

== Physical Plan ==
FileScan csv spark_demo_database.select_taxi_table[VendorID#202L,
passenger_count#203L,count#204L] 
Batched: false, DataFilters: [], Format: CSV, 
Location: InMemoryFileIndex(1 paths)
[s3://amzn-s3-demo-bucket/select_taxi], 
PartitionFilters: [], PushedFilters: [], 
ReadSchema: struct<VendorID:bigint,passenger_count:bigint,count:bigint>
```

**Example : estrutura de dados do Spark**  
O exemplo a seguir mostra como usar `EXPLAIN` com uma estrutura de dados do Spark.  

```
taxi1_df=taxi_df.groupBy("VendorID", "passenger_count").count()
taxi1_df.explain("extended")
```
**Output**  

```
Calculation started (calculation_id=d2c1ebd1-f9f0-db25-8477-3effc001b309) in 
(session=24c1ebcb-57a8-861e-1023-736f5ae55386). 
Checking calculation status...

Calculation completed.
== Parsed Logical Plan ==
'Aggregate ['VendorID, 'passenger_count], 
['VendorID, 'passenger_count, count(1) AS count#321L]
+- Relation [VendorID#49L,tpep_pickup_datetime#50,tpep_dropoff_datetime#51,
passenger_count#52L,trip_distance#53,RatecodeID#54L,store_and_fwd_flag#55,
PULocationID#56L,DOLocationID#57L,payment_type#58L,fare_amount#59,
extra#60,mta_tax#61,tip_amount#62,tolls_amount#63,improvement_surcharge#64,
total_amount#65,congestion_surcharge#66,airport_fee#67] parquet

== Analyzed Logical Plan ==
VendorID: bigint, passenger_count: bigint, count: bigint
Aggregate [VendorID#49L, passenger_count#52L], 
[VendorID#49L, passenger_count#52L, count(1) AS count#321L]
+- Relation [VendorID#49L,tpep_pickup_datetime#50,tpep_dropoff_datetime#51,
passenger_count#52L,trip_distance#53,RatecodeID#54L,store_and_fwd_flag#55,
PULocationID#56L,DOLocationID#57L,payment_type#58L,fare_amount#59,extra#60,
mta_tax#61,tip_amount#62,tolls_amount#63,improvement_surcharge#64,
total_amount#65,congestion_surcharge#66,airport_fee#67] parquet

== Optimized Logical Plan ==
Aggregate [VendorID#49L, passenger_count#52L], 
[VendorID#49L, passenger_count#52L, count(1) AS count#321L]
+- Project [VendorID#49L, passenger_count#52L]
   +- Relation [VendorID#49L,tpep_pickup_datetime#50,tpep_dropoff_datetime#51,
passenger_count#52L,trip_distance#53,RatecodeID#54L,store_and_fwd_flag#55,
PULocationID#56L,DOLocationID#57L,payment_type#58L,fare_amount#59,extra#60,
mta_tax#61,tip_amount#62,tolls_amount#63,improvement_surcharge#64,
total_amount#65,congestion_surcharge#66,airport_fee#67] parquet

== Physical Plan ==
AdaptiveSparkPlan isFinalPlan=false
+- HashAggregate(keys=[VendorID#49L, passenger_count#52L], functions=[count(1)], 
output=[VendorID#49L, passenger_count#52L, count#321L])
   +- Exchange hashpartitioning(VendorID#49L, passenger_count#52L, 1000), 
      ENSURE_REQUIREMENTS, [id=#531]
      +- HashAggregate(keys=[VendorID#49L, passenger_count#52L], 
         functions=[partial_count(1)], output=[VendorID#49L, 
         passenger_count#52L, count#326L])
         +- FileScan parquet [VendorID#49L,passenger_count#52L] Batched: true, 
            DataFilters: [], Format: Parquet, 
            Location: InMemoryFileIndex(1 paths)[s3://amzn-s3-demo-bucket/
            notebooks/yellow_tripdata_2016-01.parquet], PartitionFilters: [], 
            PushedFilters: [], 
            ReadSchema: struct<VendorID:bigint,passenger_count:bigint>
```

# Registrar em log eventos de aplicação do Spark no Athena
<a name="notebooks-spark-logging"></a>

O editor de cadernos do Athena permite o registro em log padrão do Jupyter, do Spark e do Python. É possível usar `df.show()` para exibir o conteúdo do PySpark DataFrame ou usar `print("Output")` para exibir os valores na saída da célula. As saídas `stdout`, `stderr` e `results` para seus cálculos serão gravadas no local do bucket de resultados da consulta no Amazon S3.

## Registrar em log eventos de aplicação do Spark no Amazon CloudWatch
<a name="notebooks-spark-logging-logging-spark-application-events-to-amazon-cloudwatch"></a>

As sessões do Athena também podem gravar logs no [Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) na conta que você está usando.

### Entender fluxos de logs e grupos de logs
<a name="notebooks-spark-logging-understanding-log-streams-and-log-groups"></a>

O CloudWatch organiza a atividade de log em fluxos de logs e grupos de logs.

**Fluxos de logs**: um fluxo de logs do CloudWatch corresponde a uma sequência de eventos de logs que compartilham a mesma origem. Cada origem separada de logs no CloudWatch Logs compõe um fluxo de logs separado.

**Grupos de logs**: no CloudWatch Logs, um grupo de logs corresponde a um grupo de fluxos de logs que compartilham as mesmas configurações de retenção, monitoramento e controle de acesso.

Não há limite para o número de streams de log que podem pertencer a um grupo de logs.

No Athena, quando você inicia uma sessão do caderno pela primeira vez, o Athena cria um grupo de logs no CloudWatch que usa o nome do seu grupo de trabalho habilitado para Spark, como no exemplo a seguir.

```
/aws-athena/workgroup-name
```

Esse grupo de logs recebe um fluxo de logs para cada executor em sua sessão, o que produz, no mínimo, um evento de logs. Um executor corresponde a menor unidade de computação que uma sessão do caderno pode solicitar do Athena. No CloudWatch, o nome do fluxo de logs começa com o ID da sessão e o ID do executor.

Para obter mais informações sobre os grupos de logs e os fluxos de logs do CloudWatch, consulte [Trabalhar com grupos de logs e fluxos de logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html) no Guia do usuário do Amazon CloudWatch Logs.

### Usar objetos de logger padrão no Athena para Spark
<a name="notebooks-spark-logging-using-standard-logger-objects-in-athena-for-spark"></a>

Em uma sessão do Athena para Spark, é possível usar os dois objetos logger de padrão global a seguir para gravar logs no Amazon CloudWatch:
+ **athena\$1user\$1logger**: envia logs somente para o CloudWatch. Use esse objeto quando desejar registrar em log as informações de suas aplicações Spark diretamente no CloudWatch, como no exemplo a seguir.

  ```
  athena_user_logger.info("CloudWatch log line.")
  ```

  O exemplo grava um evento de logs no CloudWatch como o seguinte:

  ```
  AthenaForApacheSpark: 2022-01-01 12:00:00,000 INFO builtins: CloudWatch log line.
  ```
+ **athena\$1shared\$1logger**: envia o mesmo log para o CloudWatch e para a AWS para fins de suporte. É possível usar esse objeto para compartilhar logs com as equipes de serviço da AWS para solução de problemas, como no exemplo a seguir.

  ```
  athena_shared_logger.info("Customer debug line.")
  var = [...some variable holding customer data...]
  athena_shared_logger.info(var)
  ```

  O exemplo registra em log a linha `debug` e o valor da variável `var` no CloudWatch Logs e envia uma cópia de cada linha para o Suporte.
**nota**  
Para sua privacidade, o código e os resultados dos cálculos não são compartilhados com a AWS. Certifique-se de que suas chamadas `athena_shared_logger` gravem somente as informações que você deseja tornar visíveis para o Suporte.

Os loggers fornecidos gravam eventos por meio do [Apache Log4j](https://logging.apache.org/log4j/) e herdam os níveis de registro em log dessa interface. Os valores de nível de log possíveis são `DEBUG`, `ERROR`, `FATAL`, `INFO` e `WARN` ou `WARNING`. É possível usar a função nomeada correspondente no logger para produzir esses valores.

**nota**  
Não vincule novamente os nomes `athena_user_logger` ou `athena_shared_logger`. Fazer isso torna os objetos de registro em log incapazes de gravar no CloudWatch pelo restante da sessão.

### Exemplo: registrar eventos de cadernos em log no CloudWatch
<a name="notebooks-spark-logging-example-logging-notebook-events-to-cloudwatch"></a>

O procedimento a seguir mostra como registrar em log os eventos de cadernos do Athena no Amazon CloudWatch Logs.

**Para registrar em log eventos de cadernos do Athena no Amazon CloudWatch Logs**

1. Siga [Introdução ao Apache Spark no Amazon Athena](notebooks-spark-getting-started.md) para criar um grupo de trabalho habilitado para Spark no Athena com um nome exclusivo. Este tutorial usa o nome `athena-spark-example` para o grupo de trabalho.

1. Siga as etapas em [Etapa 7: criar seu próprio caderno](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook) para criar um caderno e iniciar uma nova sessão.

1. No editor de cadernos do Athena, em uma nova célula do caderno, digite o seguinte comando:

   ```
   athena_user_logger.info("Hello world.")         
   ```

1. Execute a célula.

1. Recupere o ID da sessão atual seguindo um destes procedimentos:
   + Visualize a saída da célula (por exemplo, `... session=72c24e73-2c24-8b22-14bd-443bdcd72de4`).
   + Em uma nova célula, execute o comando [mágico](notebooks-spark-magics.md) `%session_id`.

1. Salve o ID da sessão.

1. Com a mesma Conta da AWS que você está usando para executar a sessão do caderno, abra o console do CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. No painel de navegação do console do CloudWatch, escolha **Log groups** (Grupos de logs).

1. Na lista de grupos de logs, escolha o grupo de logs que tem o nome do seu grupo de trabalho do Athena habilitado para Spark, como no exemplo a seguir.

   ```
   /aws-athena/athena-spark-example
   ```

   A seção **Log streams** (Fluxos de logs) contém uma lista de um ou mais links de fluxo de logs para o grupo de trabalho. Cada nome de fluxo de logs contém o ID da sessão, o ID do executor e o UUID exclusivo separados por caracteres de barra.

   Por exemplo, se o ID da sessão for `5ac22d11-9fd8-ded7-6542-0412133d3177` e o ID do executor for `f8c22d11-9fd8-ab13-8aba-c4100bfba7e2`, o nome do fluxo de logs será semelhante ao exemplo a seguir.

   ```
   5ac22d11-9fd8-ded7-6542-0412133d3177/f8c22d11-9fd8-ab13-8aba-c4100bfba7e2/f012d7cb-cefd-40b1-90b9-67358f003d0b
   ```

1. Escolha o link do fluxo de logs para sua sessão.

1. Na página **Log events** (Eventos de logs), visualize a coluna **Message** (Mensagem).

   O evento de logs para a célula executada será semelhante ao seguinte:

   ```
   AthenaForApacheSpark: 2022-01-01 12:00:00,000 INFO builtins: Hello world.
   ```

1. Retorne ao editor de cadernos do Athena.

1. Em uma nova célula, insira o código a seguir. O código registrará em log uma variável no CloudWatch:

   ```
   x = 6
   athena_user_logger.warn(x)
   ```

1. Execute a célula.

1. Retorne à página **Log events** (Eventos de logs) do console do CloudWatch para obter um fluxo de logs semelhante.

1. O fluxo de logs agora vai conter uma entrada de evento de logs com uma mensagem como a seguinte:

   ```
   AthenaForApacheSpark: 2022-01-01 12:00:00,000 WARN builtins: 6
   ```

# Use o CloudTrail para solucionar problemas de chamadas de API de cadernos do Athena
<a name="notebooks-spark-troubleshooting-cloudtrail"></a>

Para solucionar problemas de chamadas de API de cadernos, é possível examinar os logs do Athena CloudTrail para investigar anomalias ou descobrir ações iniciadas pelos usuários. Para obter informações detalhadas sobre como usar o CloudTrail com o Athena, consulte [Registrar em log as chamadas de API do Amazon Athena com o AWS CloudTrail](monitor-with-cloudtrail.md).

Os exemplos a seguir mostram entradas de log do CloudTrail para APIs de cadernos do Athena.

## StartSession
<a name="notebooks-spark-troubleshooting-cloudtrail-startsession"></a>

O exemplo a seguir mostra o log do CloudTrail para um evento [StartSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartSession.html) do caderno.

```
{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "EXAMPLE_PRINCIPAL_ID:alias",
        "arn": "arn:aws:sts::123456789012:assumed-role/Admin/alias",
        "accountId": "123456789012",
        "accessKeyId": "EXAMPLE_KEY_ID",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "EXAMPLE_PRINCIPAL_ID",
                "arn": "arn:aws:iam::123456789012:role/Admin",
                "accountId": "123456789012",
                "userName": "Admin"
            },
            "webIdFederationData": {},
            "attributes": {
                "creationDate": "2022-10-14T16:41:51Z",
                "mfaAuthenticated": "false"
            }
        }
    },
    "eventTime": "2022-10-14T17:05:36Z",
    "eventSource": "athena.amazonaws.com",
    "eventName": "StartSession",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "203.0.113.10",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
    "requestParameters": {
        "workGroup": "notebook-workgroup",
        "engineConfiguration": {
            "coordinatorDpuSize": 1,
            "maxConcurrentDpus": 20,
            "defaultExecutorDpuSize": 1,
            "additionalConfigs": {
                "NotebookId": "b8f5854b-1042-4b90-9d82-51d3c2fd5c04",
                "NotebookIframeParentUrl": "https://us-east-1.console.aws.amazon.com"
            }
        },
        "notebookVersion": "KeplerJupyter-1.x",
        "sessionIdleTimeoutInMinutes": 20,
        "clientRequestToken": "d646ff46-32d2-42f0-94d1-d060ec3e5d78"
    },
    "responseElements": {
        "sessionId": "a2c1ebba-ad01-865f-ed2d-a142b7451f7e",
        "state": "CREATED"
    },
    "requestID": "d646ff46-32d2-42f0-94d1-d060ec3e5d78",
    "eventID": "b58ce998-eb89-43e9-8d67-d3d8e30561c9",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management",
    "tlsDetails": {
        "tlsVersion": "TLSv1.2",
        "cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
        "clientProvidedHostHeader": "athena.us-east-1.amazonaws.com"
    },
    "sessionCredentialFromConsole": "true"
}
```

## TerminateSession
<a name="notebooks-spark-troubleshooting-cloudtrail-terminatesession"></a>

O exemplo a seguir mostra o log do CloudTrail para um evento [TerminateSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_TerminateSession.html) do caderno.

```
{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "EXAMPLE_PRINCIPAL_ID:alias",
        "arn": "arn:aws:sts::123456789012:assumed-role/Admin/alias",
        "accountId": "123456789012",
        "accessKeyId": "EXAMPLE_KEY_ID",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "EXAMPLE_PRINCIPAL_ID",
                "arn": "arn:aws:iam::123456789012:role/Admin",
                "accountId": "123456789012",
                "userName": "Admin"
            },
            "webIdFederationData": {},
            "attributes": {
                "creationDate": "2022-10-14T16:41:51Z",
                "mfaAuthenticated": "false"
            }
        }
    },
    "eventTime": "2022-10-14T17:21:03Z",
    "eventSource": "athena.amazonaws.com",
    "eventName": "TerminateSession",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "203.0.113.11",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
    "requestParameters": {
        "sessionId": "a2c1ebba-ad01-865f-ed2d-a142b7451f7e"
    },
    "responseElements": {
        "state": "TERMINATING"
    },
    "requestID": "438ea37e-b704-4cb3-9a76-391997cf42ee",
    "eventID": "49026c5a-bf58-4cdb-86ca-978e711ad238",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management",
    "tlsDetails": {
        "tlsVersion": "TLSv1.2",
        "cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
        "clientProvidedHostHeader": "athena.us-east-1.amazonaws.com"
    },
    "sessionCredentialFromConsole": "true"
}
```

## ImportNotebook
<a name="notebooks-spark-troubleshooting-cloudtrail-importnotebook"></a>

O exemplo a seguir mostra o log do CloudTrail para um evento [ImportNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_ImportNotebook.html) do caderno. Por segurança, alguns conteúdos foram ocultados.

```
{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "EXAMPLE_PRINCIPAL_ID:alias",
        "arn": "arn:aws:sts::123456789012:assumed-role/Admin/alias",
        "accountId": "123456789012",
        "accessKeyId": "EXAMPLE_KEY_ID",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "EXAMPLE_PRINCIPAL_ID",
                "arn": "arn:aws:iam::123456789012:role/Admin",
                "accountId": "123456789012",
                "userName": "Admin"
            },
            "webIdFederationData": {},
            "attributes": {
                "creationDate": "2022-10-14T16:41:51Z",
                "mfaAuthenticated": "false"
            }
        }
    },
    "eventTime": "2022-10-14T17:08:54Z",
    "eventSource": "athena.amazonaws.com",
    "eventName": "ImportNotebook",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "203.0.113.12",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
    "requestParameters": {
        "workGroup": "notebook-workgroup",
        "name": "example-notebook-name",
        "payload": "HIDDEN_FOR_SECURITY_REASONS",
        "type": "IPYNB",
        "contentMD5": "HIDDEN_FOR_SECURITY_REASONS"
    },
    "responseElements": {
        "notebookId": "05f6225d-bdcc-4935-bc25-a8e19434652d"
    },
    "requestID": "813e777f-6dac-41f4-82a7-e99b7b33f319",
    "eventID": "4abec837-143b-4458-9c1f-fa9fb88ab69b",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management",
    "tlsDetails": {
        "tlsVersion": "TLSv1.2",
        "cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
        "clientProvidedHostHeader": "athena.us-east-1.amazonaws.com"
    },
    "sessionCredentialFromConsole": "true"
}
```

## UpdateNotebook
<a name="notebooks-spark-troubleshooting-cloudtrail-updatenotebook"></a>

O exemplo a seguir mostra o log do CloudTrail para um evento [UpdateNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_UpdateNotebook.html) do caderno. Por segurança, alguns conteúdos foram ocultados.

```
{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "EXAMPLE_PRINCIPAL_ID:AthenaExecutor-9cc1ebb2-aac5-b1ca-8247-5d827bd8232f",
        "arn": "arn:aws:sts::123456789012:assumed-role/AWSAthenaSparkExecutionRole-om0yj71w5l/AthenaExecutor-9cc1ebb2-aac5-b1ca-8247-5d827bd8232f",
        "accountId": "123456789012",
        "accessKeyId": "EXAMPLE_KEY_ID",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "EXAMPLE_PRINCIPAL_ID",
                "arn": "arn:aws:iam::123456789012:role/service-role/AWSAthenaSparkExecutionRole-om0yj71w5l",
                "accountId": "123456789012",
                "userName": "AWSAthenaSparkExecutionRole-om0yj71w5l"
            },
            "webIdFederationData": {},
            "attributes": {
                "creationDate": "2022-10-14T16:48:06Z",
                "mfaAuthenticated": "false"
            }
        }
    },
    "eventTime": "2022-10-14T16:52:22Z",
    "eventSource": "athena.amazonaws.com",
    "eventName": "UpdateNotebook",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "203.0.113.13",
    "userAgent": "Boto3/1.24.84 Python/3.8.14 Linux/4.14.225-175.364.amzn2.aarch64 Botocore/1.27.84",
    "requestParameters": {
        "notebookId": "c87553ff-e740-44b5-884f-a70e575e08b9",
        "payload": "HIDDEN_FOR_SECURITY_REASONS",
        "type": "IPYNB",
        "contentMD5": "HIDDEN_FOR_SECURITY_REASONS",
        "sessionId": "9cc1ebb2-aac5-b1ca-8247-5d827bd8232f"
    },
    "responseElements": null,
    "requestID": "baaba1d2-f73d-4df1-a82b-71501e7374f1",
    "eventID": "745cdd6f-645d-4250-8831-d0ffd2fe3847",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management",
    "tlsDetails": {
        "tlsVersion": "TLSv1.2",
        "cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
        "clientProvidedHostHeader": "athena.us-east-1.amazonaws.com"
    }
}
```

## StartCalculationExecution
<a name="notebooks-spark-troubleshooting-cloudtrail-startcalculationexecution"></a>

O exemplo a seguir mostra o log do CloudTrail para um evento [StartCalculationExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartCalculationExecution.html) do caderno. Por segurança, alguns conteúdos foram ocultados.

```
{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "EXAMPLE_PRINCIPAL_ID:AthenaExecutor-9cc1ebb2-aac5-b1ca-8247-5d827bd8232f",
        "arn": "arn:aws:sts::123456789012:assumed-role/AWSAthenaSparkExecutionRole-om0yj71w5l/AthenaExecutor-9cc1ebb2-aac5-b1ca-8247-5d827bd8232f",
        "accountId": "123456789012",
        "accessKeyId": "EXAMPLE_KEY_ID",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "EXAMPLE_PRINCIPAL_ID",
                "arn": "arn:aws:iam::123456789012:role/service-role/AWSAthenaSparkExecutionRole-om0yj71w5l",
                "accountId": "123456789012",
                "userName": "AWSAthenaSparkExecutionRole-om0yj71w5l"
            },
            "webIdFederationData": {},
            "attributes": {
                "creationDate": "2022-10-14T16:48:06Z",
                "mfaAuthenticated": "false"
            }
        }
    },
    "eventTime": "2022-10-14T16:52:37Z",
    "eventSource": "athena.amazonaws.com",
    "eventName": "StartCalculationExecution",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "203.0.113.14",
    "userAgent": "Boto3/1.24.84 Python/3.8.14 Linux/4.14.225-175.364.amzn2.aarch64 Botocore/1.27.84",
    "requestParameters": {
        "sessionId": "9cc1ebb2-aac5-b1ca-8247-5d827bd8232f",
        "description": "Calculation started via Jupyter notebook",
        "codeBlock": "HIDDEN_FOR_SECURITY_REASONS",
        "clientRequestToken": "0111cd63-4fd0-4ad8-a738-fd350115fc21"
    },
    "responseElements": {
        "calculationExecutionId": "82c1ebb4-bd08-e4c3-5631-a662fb2ff2c5",
        "state": "CREATING"
    },
    "requestID": "1a107461-3f1b-481e-b8a2-7fbd524e2373",
    "eventID": "b74dbd00-e839-4bd1-a1da-b75fbc70ab9a",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management",
    "tlsDetails": {
        "tlsVersion": "TLSv1.2",
        "cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
        "clientProvidedHostHeader": "athena.us-east-1.amazonaws.com"
    }
}
```

# Superar o limite de tamanho de bloco de código de 68 mil
<a name="notebooks-spark-troubleshooting-code-block-size-limit"></a>

O Athena para Spark tem um limite de tamanho de bloco de código de cálculo conhecido de 68 mil caracteres. Ao executar um cálculo com um bloco de código acima desse limite, você poderá receber a seguinte mensagem de erro:

 “…” em “codeBlock” não atende à restrição: o tamanho do membro deve ser menor ou igual a 68.000

A imagem a seguir mostra esse erro no editor de caderno do console do Athena.

![\[Mensagem de erro sobre o tamanho do bloco de código no editor de caderno do Athena\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/notebooks-spark-troubleshooting-code-block-size-limit-1.png)


O mesmo erro pode ocorrer quando você usa a AWS CLI para executar um cálculo que tenha um bloco de código grande, como no exemplo a seguir.

```
aws athena start-calculation-execution \ 
    --session-id "{SESSION_ID}" \ 
    --description "{SESSION_DESCRIPTION}" \ 
    --code-block "{LARGE_CODE_BLOCK}"
```

O comando apresenta a seguinte mensagem de erro:

*\$1LARGE\$1CODE\$1BLOCK\$1* em “codeBlock” não atende à restrição: o tamanho do membro deve ser menor ou igual a 68.000

## Solução temporária
<a name="notebooks-spark-troubleshooting-code-block-size-limit-workaround"></a>

Para resolver esse problema, carregue o arquivo que contém a consulta ou o código do cálculo para o Amazon S3. Em seguida, use o boto3 para ler o arquivo e executar o SQL ou código.

Os exemplos a seguir pressupõem que você já carregou o arquivo que contém a consulta SQL ou o código Python no Amazon S3.

### Exemplo de SQL
<a name="notebooks-spark-troubleshooting-code-block-size-limit-sql-example"></a>

O código de exemplo a seguir lê o arquivo `large_sql_query.sql` em um bucket do Amazon S3 e executa a consulta grande que o arquivo contém.

```
s3 = boto3.resource('s3') 
def read_s3_content(bucket_name, key): 
    response = s3.Object(bucket_name, key).get() 
    return response['Body'].read() 

# SQL 
sql = read_s3_content('bucket_name', 'large_sql_query.sql') 
df = spark.sql(sql)
```

### Exemplo do PySpark
<a name="notebooks-spark-troubleshooting-code-block-size-limit-pyspark-example"></a>

O código de exemplo a seguir lê o arquivo `large_py_spark.py` no Amazon S3 e executa o bloco de código grande que está no arquivo.

```
s3 = boto3.resource('s3') 
 
def read_s3_content(bucket_name, key): 
    response = s3.Object(bucket_name, key).get() 
    return response['Body'].read() 
     
# PySpark 
py_spark_code = read_s3_content('bucket_name', 'large_py_spark.py') 
exec(py_spark_code)
```

# Solucionar erros de sessão
<a name="notebooks-spark-troubleshooting-sessions"></a>

Use as informações desta seção para solucionar problemas de sessão.

Quando ocorre um erro de configuração personalizada durante o início da sessão, o console do Athena para Spark mostra um banner de mensagem de erro. Para solucionar erros de início de sessão, verifique a alteração do estado da sessão ou as informações de registro.

## Visualizar informações sobre alterações de estado da sessão
<a name="notebooks-spark-troubleshooting-sessions-viewing-session-state-change"></a>

Você pode obter detalhes sobre uma alteração no estado da sessão no editor do caderno do Athena ou na API do Athena.

**Para visualizar as informações do estado da sessão no console do Athena**

1. No editor de cadernos do Athena, no menu **Sessão** no canto superior direito, escolha **Visualizar detalhes**.

1. Visualize a guia **Sessão atual**. A seção **Informações da sessão** exibe informações como ID da sessão, grupo de trabalho, status e motivo da mudança de estado.

   O exemplo de captura de tela a seguir mostra informações na seção **Motivo da mudança de estado** da caixa de diálogo **Informações da sessão** para um erro de sessão do Spark no Athena.  
![\[Visualizar as informações do estado da sessão no console do Athena para Spark.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/notebooks-spark-custom-jar-cfg-1.jpeg)

**Para visualizar as informações do estado da sessão usando a API do Athena**
+ Na API do Athena, você pode encontrar informações sobre alteração do estado da sessão no campo `StateChangeReason` do objeto [SessionStatus](https://docs.aws.amazon.com/athena/latest/APIReference/API_SessionStatus.html).

**nota**  
Após interromper manualmente uma sessão ou se a sessão for interrompida após um tempo limite de inatividade (o padrão é 20 minutos), o valor de **StateChangeReason** é alterado para A sessão foi encerrada por solicitação.

## Usar registro em log para solucionar erros de início de sessão
<a name="notebooks-spark-troubleshooting-sessions-using-logging"></a>

Os erros de configuração personalizada que ocorrem durante o início da sessão são registrados em log pelo [Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html). No CloudWatch Logs, pesquise mensagens de erro de `AthenaSparkSessionErrorLogger` para solucionar uma falha no início da sessão.

Para obter mais informações sobre registro em log, consulte [Registrar em log eventos de aplicação do Spark no Athena](notebooks-spark-logging.md).

Para obter mais informações sobre sessões de solução de problemas no Athena para Spark, consulte [Solucionar erros de sessão](#notebooks-spark-troubleshooting-sessions).

## Problemas específicos da sessão
<a name="notebooks-spark-troubleshooting-sessions-specific-error-messages"></a>

Use as informações desta seção para solucionar alguns problemas específicos da sessão.

### Sessão em estado não íntegro
<a name="notebooks-spark-troubleshooting-sessions-unhealthy"></a>

Se você receber a mensagem de erro: Session in unhealthy state. Please create a new session (Sessão em estado não íntegro. Crie uma nova sessão.), encerre a sessão existente e crie uma nova.

### Não foi possível estabelecer uma conexão com o servidor do caderno
<a name="notebooks-spark-troubleshooting-sessions-wss-blocked"></a>

Ao abrir um caderno, é possível visualizar a mensagem de erro a seguir:

```
A connection to the notebook server could not be established.  
The notebook will continue trying to reconnect.  
Check your network connection or notebook server configuration.
```

#### Causa
<a name="notebooks-spark-troubleshooting-sessions-wss-blocked-cause"></a>

Quando o Athena abre um caderno, ele cria uma sessão e se conecta ao caderno usando um URL previamente conectado para o caderno. A conexão com o caderno usa o protocolo WSS ([WebSocket Secure](https://en.wikipedia.org/wiki/WebSocket)).

O erro pode ocorrer pelos seguintes motivos:
+ Um firewall local (por exemplo, um firewall que abrange toda a empresa) está bloqueando o tráfego WSS.
+ O software proxy ou antivírus em seu computador local está bloqueando a conexão WSS.

#### Solução
<a name="notebooks-spark-troubleshooting-sessions-wss-blocked-solution"></a>

Suponha que você tenha uma conexão WSS na região `us-east-1`, que é semelhante a seguir:

```
wss://94c2bcdf-66f9-4d17-9da6-7e7338060183.analytics-gateway.us-east-1.amazonaws.com/
api/kernels/33c78c82-b8d2-4631-bd22-1565dc6ec152/channels?session_id=
7f96a3a048ab4917b6376895ea8d7535
```

Para resolver o erro, use uma das seguintes estratégias.
+ Use a sintaxe padrão de caráter universal para permitir a listagem do tráfego WSS na porta `443` entre as Regiões da AWS e as Contas da AWS.

  ```
  wss://*amazonaws.com
  ```
+ Use a sintaxe padrão de caráter universal para permitir a listagem do tráfego WSS na porta `443` em uma Região da AWS e entre as Contas da AWS na Região da AWS que você especificar. O exemplo a seguir usa `us-east-1`.

  ```
  wss://*analytics-gateway.us-east-1.amazonaws.com
  ```

# Solucionar erros de tabela
<a name="notebooks-spark-troubleshooting-tables"></a>

Use as informações desta seção para solucionar erros de tabela do Athena para Spark.

## Não é possível criar um caminho, ocorre um erro ao criar uma tabela
<a name="notebooks-spark-troubleshooting-tables-illegal-argument-exception"></a>

**Mensagem de erro**: IllegalArgumentException: Cannot create a path from an empty string (IllegalArgumentException: não é possível criar um caminho usando uma string vazia).

**Causa**: esse erro pode ocorrer quando você usa o Apache Spark no Athena para criar uma tabela em um banco de dados do AWS Glue, e o banco de dados tem uma propriedade `LOCATION` vazia. 

**Solução sugerida**: para obter mais informações e soluções, consulte [Exceção para argumento inválido ao criar uma tabela](notebooks-spark-known-issues.md#notebooks-spark-known-issues-illegal-argument-exception).

## AccessDeniedException ao consultar tabelas do AWS Glue
<a name="notebooks-spark-troubleshooting-tables-glue-access-denied"></a>

**Mensagem de erro**: pyspark.sql.utils.AnalysisException: Unable to verify existence of default database: com.amazonaws.services.glue.model.AccessDeniedException: User: arn:aws:sts::*aws-account-id*:assumed-role/AWSAthenaSparkExecutionRole-*unique-identifier*/AthenaExecutor-*unique-identifier* is not authorized to perform: glue:GetDatabase on resource: arn:aws:glue:*aws-region*:*aws-account-id*:catalog because no identity-based policy allows the glue:GetDatabase action (Service: AWSGlue; Status Code: 400; Error Code: AccessDeniedException; Request ID: *request-id*; Proxy: null) (pyspark.sql.utils.AnalysisException: não é possível verificar a existência do banco de dados padrão: com.amazonaws.services.glue.model.AccessDeniedException: o usuário: arn:aws:sts::aws-account-id:assumed-role/AWSAthenaSparkExecutionRole-unique -identifier/AthenaExecutor-unique-identifier não está autorizado a executar: glue:GetDatabase no recurso: arn:aws:glue:aws-region:aws-account-id:catalog porque nenhuma política baseada em identidade permite a ação glue:GetDatabase (serviço: AWSGlue; código de status: 400; código de erro: AccessDeniedException; ID da solicitação: request-id; proxy: nulo).

**Causa**: o perfil de execução do grupo de trabalho habilitado para Spark não tem permissões para acessar os recursos do AWS Glue.

**Solução sugerida**: para resolver esse problema, conceda ao perfil de execução acesso aos recursos do AWS Glue e, em seguida, edite a política de bucket do Amazon S3 para conceder acesso ao perfil de execução.

O procedimento a seguir descreve essas etapas com mais detalhes.

**Para conceder acesso aos recursos do AWS Glue ao perfil de execução**

1. Abra o console do Athena em [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home).

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 do console do Athena, escolha **Workgroups** (Grupos de trabalho).

1. Na página **Workgroups** (Grupos de trabalho), escolha o link do grupo de trabalho que você deseja visualizar.

1. Na página **Overview Details** (Detalhes gerais) para o grupo de trabalho, escolha o link **Role ARN** (ARN do perfil). O link abrirá o perfil de execução do Spark no console do IAM.

1. Na seção **Permissions policies** (Políticas de permissões), escolha o nome da política de perfil vinculada.

1. Escolha **Edit policy** (Editar política) e, em seguida, selecione **JSON**.

1. Adicione o acesso ao AWS Glue para o perfil. Normalmente, você adiciona permissões para as ações `glue:GetDatabase` e `glue:GetTable`. Para obter mais informações sobre como configurar perfis do IAM, consulte [Adicionar e remover permissões de identidade do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) no Guia do usuário do IAM. 

1. Selecione **Review policy (Revisar política)** e, em seguida, escolha, **Save changes (Salvar alterações)**.

1. Edite a política de bucket do Amazon S3 para conceder acesso ao perfil de execução. Observe que é necessário conceder ao perfil acesso tanto ao bucket quanto aos objetos do bucket. Para visualizar as etapas, consulte [Adicionar uma política de bucket usando o console do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/add-bucket-policy.html) no Guia do usuário do Amazon Simple Storage Service.

# Obter suporte
<a name="notebooks-spark-troubleshooting-support"></a>

Para obter assistência da AWS, escolha **Support** (Suporte), na **Support Center** (Central de suporte) no Console de gerenciamento da AWS. Para facilitar sua experiência, tenha em mãos as informações a seguir:
+ ID da consulta do Athena
+ ID da sessão
+ ID do cálculo