# Referência do SQL para o Athena O Amazon Athena oferece um subconjunto de instruções, funções, operadores e tipos de dados em Data Definition Language (DDL – Linguagem de definição de dados) e Data Manipulation Language (DML – Linguagem de manipulação de dados). Com algumas exceções, a DDL do Athena é baseada na [DDL do HiveQL](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL) e a DML do Athena é baseada no [Trino](https://trino.io/docs/current/language.html). Para obter informações sobre as versões do mecanismo do Athena, consulte [Versionamento do mecanismo do Athena](engine-versions.md). **Topics** + [Tipos de dados no Athena](data-types.md) + [Consultas, funções e operadores em DML](dml-queries-functions-operators.md) + [Instruções DDL](ddl-reference.md) + [Considerações e limitações](other-notable-limitations.md) # Tipos de dados no Amazon Athena Ao executar `CREATE TABLE`, você especifica os nomes de coluna e o tipo de dados que cada coluna pode conter. As tabelas que você cria são armazenadas no AWS Glue Data Catalog. Para facilitar a interoperabilidade com outros mecanismos de consulta, o Athena usa nomes de tipos de dados do [Apache Hive](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types) para instruções DDL, como `CREATE TABLE`. Para consultas DML como `SELECT`, `CTAS` e `INSERT INTO`, o Athena usa nomes de tipo de dados [Trino](https://trino.io/docs/current/language/types.html). A tabela a seguir mostra os tipos de dados compatíveis com o Athena. Quando os tipos DDL e DML forem diferentes em termos de nome, disponibilidade ou sintaxe, eles serão apresentados em colunas separadas. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/data-types.html) **Topics** + [Exemplos de tipo de dados](data-types-examples.md) + [Considerações sobre tipos de dados](data-types-considerations.md) + [Trabalhar com dados de timestamp](data-types-timestamps.md) # Exemplos de tipo de dados A tabela a seguir apresenta exemplos de literais para tipos de dados DML. **** | Tipo de dados | Exemplos | | --- | --- | | BOOLEAN | `true` `false ` | | TINYINT | `TINYINT '123'` | | SMALLINT | `SMALLINT '123'` | | INT, INTEGER | `123456790` | | BIGINT | `BIGINT '1234567890'` `2147483648` | | REAL | `'123456.78'` | | DOUBLE | `1.234` | | DECIMAL(precisão, escala) | `DECIMAL '123.456'` | | CHAR, CHAR(comprimento) | `CHAR 'hello world'`, `CHAR 'hello ''world''!'` | | VARCHAR, VARCHAR(comprimento) | `VARCHAR 'hello world'`, `VARCHAR 'hello ''world''!'` | | VARBINARY | `X'00 01 02'` | | TIME, TIME(precisão) | `TIME '10:11:12'`, `TIME '10:11:12.345'` | | TIME WITH TIME ZONE | `TIME '10:11:12.345 -06:00'` | | DATE | `DATE '2024-03-25'` | | TIMESTAMP, TIMESTAMP WITHOUT TIME ZONE, TIMESTAMP(*precisão*), TIMESTAMP(*precisão*) WITHOUT TIME ZONE | `TIMESTAMP '2024-03-25 11:12:13'`, `TIMESTAMP '2024-03-25 11:12:13.456'` | | TIMESTAMP WITH TIME ZONE, TIMESTAMP(precisão) WITH TIME ZONE | `TIMESTAMP '2024-03-25 11:12:13.456 Europe/Berlin'` | | INTERVALO ENTRE UM ANO E UM MÊS | `INTERVAL '3' MONTH` | | INTERVALO ENTRE UM DIA E UM SEGUNDO | `INTERVAL '2' DAY` | | ARRAY[tipo\$1elemento] | `ARRAY['one', 'two', 'three']` | | MAP(tipo\$1chave, tipo\$1valor) | `MAP(ARRAY['one', 'two', 'three'], ARRAY[1, 2, 3])` Observe que os mapas são criados com base em uma matriz de chaves e uma matriz de valores. O exemplo a seguir cria uma tabela que mapeia strings para números inteiros. 
CREATE TABLE map_table(col1 map) LOCATION '...';
INSERT INTO map_table values(MAP(ARRAY['foo', 'bar'], ARRAY[1, 2]));
| | ROW(nome\$1campo\$11:tipo\$1campo\$11, nome\$1campo\$12:tipo\$1campo\$12, …) | `ROW('one', 'two', 'three')` Observe que as linhas criadas dessa forma não têm nomes de colunas. Para adicionar nomes de colunas, você pode usar `CAST`, como no exemplo a seguir: 
CAST(ROW(1, 2, 3) AS ROW(one INT, two INT, three INT))
| | JSON | `JSON '{"one":1, "two": 2, "three": 3}'` | | UUID | `UUID '12345678-90ab-cdef-1234-567890abcdef'` | | IPADDRESS | `IPADDRESS '10.0.0.1'` `IPADDRESS '2001:db8::1'` | # Considerações sobre tipos de dados ## Limites de tamanho Para tipos de dados que não especificam um limite de tamanho, lembre-se de que há um limite prático de 32 MB para todos os dados em uma única linha. Para obter mais informações, consulte [Row or column size limitation](other-notable-limitations.md#sql-limitations-rowsize) em [Considerações e limitações das consultas SQL no Amazon Athena](other-notable-limitations.md). ## CHAR e VARCHAR Um valor `CHAR(n)` sempre tem uma contagem de `n` caracteres. Por exemplo, se você lançar “abc” para `CHAR(7)`, 4 espaços finais serão adicionados. As comparações de valores `CHAR` incluem espaços à esquerda e à direita. Se um comprimento for especificado para `CHAR` ou `VARCHAR`, as strings serão truncadas no comprimento especificado quando lidas. Se a string de dados subjacente for mais longa, a string de dados subjacente permanecerá inalterada. Para escapar uma aspas simples em um `CHAR` ou `VARCHAR`, use uma aspas simples adicional. Para converter um tipo de dados que não seja uma string em uma consulta DML, converta para o tipo de dados `VARCHAR`. Para usar a função `substr` para retornar uma substring de comprimento específico proveniente de um tipo de dados `CHAR`, primeiro é necessário lançar o valor `CHAR` como `VARCHAR`. No exemplo a seguir, `col1` usa o tipo de dados `CHAR`. ``` substr(CAST(col1 AS VARCHAR), 1, 4) ``` ## DECIMAL Para especificar valores decimais como literais em consultas `SELECT`, como ao selecionar linhas com um valor decimal específico, é possível especificar o tipo `DECIMAL` e listar o valor decimal como um literal entre aspas simples na consulta, como nos exemplos a seguir. ``` SELECT * FROM my_table WHERE decimal_value = DECIMAL '0.12' ``` ``` SELECT DECIMAL '44.6' + DECIMAL '77.2' ``` # Trabalhar com dados de timestamp Esta seção descreve algumas considerações para trabalhar com dados de timestamp no Athena. **nota** O tratamento dos timestamps mudou um pouco entre as versões anteriores do mecanismo do Athena e o mecanismo do Athena versão 3. Para obter informações sobre erros relacionados ao timestamp que podem ocorrer no mecanismo do Athena versão 3 e soluções sugeridas, consulte [Alterações de timestamp](engine-versions-reference-0003.md#engine-versions-reference-0003-timestamp-changes) na referência [Mecanismo Athena versão 3](engine-versions-reference-0003.md). ## Formato para gravar dados de timestamp em objetos do Amazon S3 O formato no qual os dados de timestamp devem ser gravados em objetos do Amazon S3 depende do tipo de dados da coluna e da [biblioteca SerDe](https://docs.aws.amazon.com/athena/latest/ug/supported-serdes.html) utilizada. + Se você tiver uma coluna de tabela do tipo `DATE`, o Athena espera que a coluna ou propriedade correspondente dos dados seja uma string no formato ISO `YYYY-MM-DD` ou um tipo de data incorporado, como aqueles para Parquet ou ORC. + Se você tiver uma coluna de tabela do tipo `TIME`, o Athena espera que a coluna ou propriedade correspondente dos dados seja uma string no formato ISO `HH:MM:SS` ou um tipo de hora incorporado, como aqueles para Parquet ou ORC. + Se você tiver uma coluna de tabela do tipo `TIMESTAMP`, o Athena espera que a coluna ou propriedade correspondente dos dados seja uma string no formato `YYYY-MM-DD HH:MM:SS.SSS` (observe o espaço entre a data e a hora) ou um tipo de hora incorporado, como aqueles para Parquet, ORC ou Ion. Observe que o Athena não garante o comportamento com timestamps inválidos (por exemplo `0000-00-00 08:00:00.000`). **nota** Os timestamps do OpenCsvSerDe são uma exceção e devem ser codificados como epochs UNIX com resolução de milissegundos. ## Garantir que os dados particionados por tempo correspondam ao campo de timestamp em um registro O produtor dos dados deve garantir que os valores da partição estejam alinhados com os dados na partição. Por exemplo, se os dados tiverem uma propriedade `timestamp` e você usar o Firehose para carregá-los no Amazon S3, será necessário usar o [particionamento dinâmico](https://docs.aws.amazon.com/firehose/latest/dev/dynamic-partitioning.html) porque o particionamento padrão do Firehose é baseado em hora real do relógio. ## Usar string como o tipo de dados para chaves de partição Por motivos de performance, é preferível usar `STRING` como tipo de dados para chaves de partição. Embora o Athena reconheça valores de partição no formato `YYYY-MM-DD` como datas quando você usa o tipo `DATE`, isso pode levar a uma performance ruim. Por isso, recomenda-se usar o tipo de dados `STRING` para chaves de partição. ## Como gravar consultas em campos de timestamp que também são particionados por tempo A forma como você grava consultas em campos de timestamp que são particionados por hora depende do tipo de tabela que você deseja consultar. ### Tabelas Hive Com as tabelas Hive mais usadas no Athena, o mecanismo de consulta não tem conhecimento das relações entre as colunas e as chaves de partição. Por isso, você sempre deve adicionar predicados às consultas tanto para a coluna como para a chave de partição. Por exemplo, suponha que você tenha uma coluna `event_time` e uma chave de partição `event_date` e queira consultar eventos entre 23:00 e 03:00. Nesse caso, é necessário incluir predicados em sua consulta para a coluna e a chave de partição, como no exemplo a seguir. ``` WHERE event_time BETWEEN start_time AND end_time AND event_date BETWEEN start_time_date AND end_time_date ``` ### Tabelas Iceberg Com as tabelas Iceberg, é possível usar valores de partição computados, o que simplifica suas consultas. Por exemplo, suponha que sua tabela do Iceberg tenha sido criada com uma cláusula `PARTITIONED BY` como esta: ``` PARTITIONED BY (event_date month(event_time)) ``` Nesse caso, o mecanismo de consulta remove automaticamente as partições com base nos valores dos predicados `event_time`. Por isso, sua consulta só precisa especificar um predicado para `event_time`, como no exemplo a seguir. ``` WHERE event_time BETWEEN start_time AND end_time ``` Para obter mais informações, consulte [Criar tabelas do Iceberg](querying-iceberg-creating-tables.md). Ao usar o particionamento oculto do Iceberg para uma coluna de timestamp, o Iceberg pode criar uma partição em uma coluna de tabela construída derivada de uma coluna de timestamp e transformada em uma data para proporcionar um particionamento mais eficaz. Por exemplo, ele pode criar `event_date` a partir da coluna de timestamp `event_time` e particionar automaticamente em `event_date`. Nesse caso, o **tipo** da partição é uma **data**. Para usufruir da performance ideal da consulta ao usar a partição, filtre por intervalos de dias inteiros para habilitar o pushdown de predicados. Por exemplo, a consulta a seguir não seria submetida a pushdown porque o intervalo não pode ser convertido em uma única partição de data, mesmo que esteja dentro de um único dia: ``` WHERE event_time >= TIMESTAMP '2024-04-18 00:00:00' AND event_time < TIMESTAMP '2024-04-18 12:00:00' ``` Em vez disso, use um intervalo de dias inteiros para permitir o pushdown de predicados e melhorar a performance da consulta, como no exemplo a seguir. ``` WHERE event_time >= TIMESTAMP '2024-04-18 00:00:00' AND event_time < TIMESTAMP '2024-04-19 00:00:00' ``` Você também pode usar a sintaxe `BETWEEN start_time AND end_time` ou usar os intervalos de vários dias, desde que as partes dos timestamps sejam `00:00:00`. Para obter mais informações, consulte a [postagem do blog do Trino](https://trino.io/blog/2023/04/11/date-predicates.html). # Consultas, funções e operadores em DML Em geral, o mecanismo de consulta DML do Athena é compatível com a sintaxe do Trino e do Presto e acrescenta suas próprias melhorias. O Athena não é compatível com todos os recursos do Trino ou Presto. Para obter mais informações, consulte os tópicos das instruções específicas nesta seção e [Considerações e limitações](other-notable-limitations.md). Para obter informações sobre as funções, consulte [Funções no Amazon Athena](functions.md). Para obter informações sobre as versões do mecanismo do Athena, consulte [Versionamento do mecanismo do Athena](engine-versions.md). Para obter mais informações sobre instruções DDL, consulte [Instruções DDL](ddl-reference.md). Para ver uma lista de instruções DDL não permitidas, consulte [DDL incompatível](unsupported-ddl.md). **Topics** + [SELECT](select.md) + [INSERT INTO](insert-into.md) + [VALUES](values-statement.md) + [DELETE](delete-statement.md) + [UPDATE](update-statement.md) + [MERGE INTO](merge-into-statement.md) + [OPTIMIZE](optimize-statement.md) + [VACUUM](vacuum-statement.md) + [EXPLAIN e EXPLAIN ANALYZE](athena-explain-statement.md) + [PREPARE](sql-prepare.md) + [UNLOAD](unload.md) + [Funções](functions.md) + [Usar fusos horários compatíveis](athena-supported-time-zones.md) # SELECT Recupera linhas de dados de zero ou mais tabelas. **nota** Este tópico fornece informações resumidas para referência. Informações abrangentes sobre o uso de `SELECT` e a linguagem SQL estão além do escopo desta documentação. Para obter informações sobre como usar o SQL específico do Athena, consulte [Considerações e limitações das consultas SQL no Amazon Athena](other-notable-limitations.md) e [Executar consultas SQL no Amazon Athena](querying-athena-tables.md). Para ver um exemplo de como criar um banco de dados, criar uma tabela e executar uma consulta `SELECT` na tabela do Athena, consulte [Conceitos básicos](getting-started.md). ## Resumo ``` [ WITH with_query [, ...] ] SELECT [ ALL | DISTINCT ] select_expression [, ...] [ FROM from_item [, ...] ] [ WHERE condition ] [ GROUP BY [ ALL | DISTINCT ] grouping_element [, ...] ] [ HAVING condition ] [ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] select ] [ ORDER BY expression [ ASC | DESC ] [ NULLS FIRST | NULLS LAST] [, ...] ] [ OFFSET count [ ROW | ROWS ] ] [ LIMIT [ count | ALL ] ] ``` **nota** Palavras reservadas em instruções SQL SELECT devem ficar entre aspas duplas. Para obter mais informações, consulte [Palavras-chave reservadas para escape e em instruções de SQL SELECT](reserved-words.md#list-of-reserved-words-sql-select). ## Parâmetros **[ WITH with\$1query [, ....] ]** Você pode usar `WITH` para nivelar consultas aninhadas ou para simplificar subconsultas. O uso da cláusula `WITH` para criar consultas recursivas é possível a partir da versão 3 do mecanismo Athena. A profundidade de recursão máxima é 10. A cláusula `WITH` precede a lista `SELECT` em uma consulta e define uma ou mais subconsultas a serem usadas dentro da consulta `SELECT`. Cada subconsulta define uma tabela temporária, semelhante a uma definição de exibição, que você pode referenciar na cláusula `FROM`. As tabelas são usadas apenas quando a consulta é executada. `with_query`A sintaxe é: ``` subquery_table_name [ ( column_name [, ...] ) ] AS (subquery) ``` Em que: + `subquery_table_name` é um nome exclusivo para uma tabela temporária que define os resultados da subconsulta de cláusula `WITH`. Cada `subquery` deve ter um nome de tabela que possa ser referenciado na cláusula `FROM`. + `column_name [, ...]` é uma lista opcional de nomes de coluna de saída. O número de nomes de coluna deve ser igual a ou menor que o número de colunas definido por `subquery`. + `subquery` é uma instrução da consulta qualquer. **[ ALL \$1 DISTINCT ] select\$1expression** `select_expression` determina as linhas a serem selecionadas. Uma `select_expression` pode usar um dos seguintes formatos: ``` expression [ [ AS ] column_alias ] [, ...] ``` ``` row_expression.* [ AS ( column_alias [, ...] ) ] ``` ``` relation.* ``` ``` * ``` + A sintaxe `expression [ [ AS ] column_alias ]` especifica uma coluna de saída. A sintaxe opcional `[AS] column_alias` especifica um nome de título personalizado a ser usado para a coluna na saída. + Para `row_expression.* [ AS ( column_alias [, ...] ) ]`, `row_expression` é uma expressão arbitrária do tipo de dados `ROW`. Os campos da linha definem as colunas de saída a serem incluídas no resultado. + Para `relation.*`, as colunas de `relation` são incluídas no resultado. Essa sintaxe não permite o uso de aliases de coluna. + O asterisco `*` especifica que todas as colunas sejam incluídas no conjunto de resultados. + No conjunto de resultados, a ordem das colunas é igual à ordem de sua especificação pela expressão de seleção. Se uma expressão de seleção retornar várias colunas, a ordem das colunas segue a ordem usada na relação de origem ou na expressão do tipo de linha. + Quando os aliases de coluna são especificados, os aliases substituem os nomes de campos de coluna ou linha pré-existentes. Se a expressão de seleção não tiver nomes de coluna, nomes de colunas anônimas com índice zero (`_col0`,`_col1` e `_col2, ...`) serão exibidos na saída. + `ALL` é o padrão. Usar `ALL` será tratado da mesma maneira como se tivesse sido omitido. Todas as linhas de todas as colunas são selecionadas, e as duplicações são mantidas. + Use `DISTINCT` para retornar somente valores distintos quando uma coluna contém valores duplicados. **FROM from\$1item [, ...]** Indica a entrada para a consulta, em que `from_item` pode ser uma exibição, um construto de união ou uma subconsulta conforme descrito abaixo. O `from_item` pode ser: + `table_name [ [ AS ] alias [ (column_alias [, ...]) ] ]` Em que `table_name` é o nome da tabela de destino da qual selecionar linhas, `alias` é o nome para indicar a saída da instrução `SELECT` e `column_alias` define as colunas para o `alias` especificado. **-OU-** + `join_type from_item [ ON join_condition | USING ( join_column [, ...] ) ]` Em que `join_type` é um dos: + `[ INNER ] JOIN` + `LEFT [ OUTER ] JOIN` + `RIGHT [ OUTER ] JOIN` + `FULL [ OUTER ] JOIN` + `CROSS JOIN` + `ON join_condition | USING (join_column [, ...])` Em que usar `join_condition` permite especificar nomes de coluna para chaves de união em várias tabelas e usar `join_column` exige que `join_column` exista em ambas as tabelas. **[ WHERE condição ]** Filtra os resultados de acordo com a `condition` que você especificar, em que `condition` costuma ter a sintaxe abaixo. ``` column_name operator value [[[AND | OR] column_name operator value] ...] ``` O *operador* pode ser um dos comparadores `=`, `>`, `<`, `>=`, `<=`, `<>`, `!=`. As expressões de subconsulta a seguir também podem ser usadas na cláusula `WHERE`. + `[NOT] BETWEEN integer_A AND integer_B`: especifica um intervalo entre dois inteiros, como no exemplo a seguir. Se o tipo de dados da coluna for `varchar`, a coluna deverá ser convertida para inteiro primeiro. ``` SELECT DISTINCT processid FROM "webdata"."impressions" WHERE cast(processid as int) BETWEEN 1500 and 1800 ORDER BY processid ``` + `[NOT] LIKE value`: pesquisa o padrão especificado. Use o sinal de porcentagem (`%`) como caractere curinga, conforme mostrado no exemplo a seguir. ``` SELECT * FROM "webdata"."impressions" WHERE referrer LIKE '%.org' ``` + `[NOT] IN (value[, value[, ...])`: especifica uma lista de valores possíveis para uma coluna, como no exemplo a seguir. ``` SELECT * FROM "webdata"."impressions" WHERE referrer IN ('example.com','example.net','example.org') ``` **[ GROUP BY [ ALL \$1 DISTINCT ] grouping\$1expressions [, ...] ]** Divide a saída da instrução `SELECT` em linhas com valores correspondentes. `ALL` e `DISTINCT` determinam se conjuntos de agrupamentos duplicados produzem linhas de saída distintas. Se omitido, `ALL` será pressuposto. `grouping_expressions` permite realizar operações de agrupamento complexas. Você pode usar operações de agrupamento complexas para realizar uma análise que exija agregação de vários conjuntos de colunas em uma única consulta. O elemento `grouping_expressions` pode ser qualquer função, como `SUM`, `AVG` ou `COUNT`, executada nas colunas de entrada. As expressões `GROUP BY` podem agrupar a saída por nomes de coluna de entrada não exibidos na saída da instrução `SELECT`. Todas as expressões de saída devem ser funções agregadas ou colunas presentes na cláusula `GROUP BY`. Você pode usar uma única consulta para realizar uma análise que exija a agregação de vários conjuntos de colunas. O Athena aceita agregações complexas que usam `GROUPING SETS`, `CUBE` e `ROLLUP`. `GROUP BY GROUPING SETS` especifica várias listas de colunas para agrupamento. `GROUP BY CUBE` gera todos os conjuntos de agrupamento possíveis para um determinado conjunto de colunas. `GROUP BY ROLLUP` gera todos os subtotais possíveis para um determinado conjunto de colunas. As operações de agrupamento complexas não permitem agrupamento de expressões compostas de colunas de entrada. Somente nomes de coluna são permitidos. Você normalmente pode usar `UNION ALL` para obter os mesmos resultados dessas operações `GROUP BY`, mas consultas que usam `GROUP BY` têm a vantagem de ler os dados uma vez, e `UNION ALL` lê os dados subjacentes três vezes e podem produzir resultados inconsistentes quando a fonte de dados está sujeita a alterações. **[ HAVING condition ]** Usada com funções de agregação e a cláusula `GROUP BY`. Controla quais grupos são selecionados, eliminando grupos que não atendam a `condition`. A filtragem ocorrerá depois de grupos, e as agregações serão calculadas. **[ \$1 UNION \$1 INTERSECT \$1 EXCEPT \$1 [ ALL \$1 DISTINCT ] union\$1query] ]** `UNION`, `INTERSECT` e `EXCEPT` combinam os resultados de mais de uma instrução `SELECT` em uma única consulta. `ALL` ou `DISTINCT` controla a exclusividade das linhas incluídas no conjunto final de resultados. `UNION` combina as linhas resultantes da primeira consulta com as linhas resultantes da segunda consulta. Para eliminar duplicatas, `UNION` cria uma tabela de hash, que consome memória. Para melhor performance, considere usar `UNION ALL` se a consulta não exigir eliminação de duplicatas. Várias cláusulas `UNION` são processadas da esquerda para a direita, a menos que você use parênteses para definir explicitamente a ordem de processamento. `INTERSECT` retorna apenas as linhas que estão presentes nos resultados da primeira e da segunda consultas. `EXCEPT` retorna as linhas dos resultados da primeira consulta, excluindo as linhas encontradas pela segunda consulta. `ALL` faz com que todas as linhas sejam incluídas, mesmo se elas forem idênticas. `DISTINCT` faz com que apenas as linhas exclusivas sejam incluídas no conjunto de resultados combinados. **[ ORDER BY expression [ ASC \$1 DESC ] [ NULLS FIRST \$1 NULLS LAST] [, ...] ]** Classifica um conjunto de resultados por um ou mais de saída `expression`. Quando a cláusula contém várias expressões, o conjunto de resultados é classificado de acordo com o primeiro `expression`. Em seguida, o segundo `expression` é aplicado a linhas que tenham valores correspondentes da primeira expressão, e assim por diante. Cada `expression` pode especificar colunas de saída de `SELECT` ou um número ordinal para uma coluna de saída por posição, a partir de um. `ORDER BY` é avaliada como a última etapa após qualquer cláusula `GROUP BY` ou `HAVING`. `ASC` e `DESC` determinam se os resultados são classificados em ordem crescente ou decrescente. A ordem de classificação padrão é a ordem decrescente (`ASC`). A ordem nula padrão é `NULLS LAST`, independentemente da ordem de classificação crescente ou decrescente. **[ Contagem de DESLOCAMENTO [ LINHA \$1 LINHAS ] ]** Use a cláusula `OFFSET` para descartar várias linhas iniciais do conjunto de resultados. Se a cláusula `ORDER BY` estiver presente, a cláusula `OFFSET` será avaliada em um conjunto de resultados classificados e o conjunto permanecerá classificado após as linhas ignoradas serem descartadas. Se a consulta não tiver cláusula `ORDER BY`, a definição de quais linhas serão descartadas é arbitrária. Se a contagem especificada por `OFFSET` for igual ou exceder o tamanho do conjunto de resultados, o resultado final será vazio. **LIMIT [ count \$1 ALL ]** Restringe o número de linhas no conjunto de resultados a `count`. `LIMIT ALL` é igual à omissão da cláusula `LIMIT`. Se a consulta não tiver a cláusula `ORDER BY`, os resultados serão arbitrários. **TABLESAMPLE [ BERNOULLI \$1 SYSTEM ] (porcentagem)** Operador operacional para selecionar linhas de uma tabela com base em um método de amostragem. `BERNOULLI` seleciona cada linha para estar no exemplo da tabela com uma probabilidade de `percentage`. Todos os blocos físicos da tabela são examinados, e determinadas linhas são ignoradas com base em uma comparação entre o `percentage` de exemplo e um valor aleatório calculado no runtime Com `SYSTEM`, a tabela é dividida em segmentos lógicos de dados, e a tabela mostra um exemplo dessa granularidade. Todas as linhas de um determinado segmento são selecionadas, ou o segmento é ignorado com base em uma comparação entre o `percentage` de exemplo e um valor aleatório calculado no runtime. A amostragem de `SYSTEM` depende do conector. Esse método não garante probabilidades de amostragem independentes. **[ UNNEST (array\$1or\$1map) [WITH ORDINALITY] ]** Expande uma matriz ou um mapa para uma relação. As matrizes são expandidas para uma única coluna. Os mapas são expandidos para duas colunas (*chave*, *valor*). Você pode usar `UNNEST` com vários argumentos, que são expandidos para várias colunas com o máximo de linhas do maior argumento de cardinalidade. Outras colunas são preenchidas com nulos. A cláusula `WITH ORDINALITY` adiciona uma coluna de ordinalidade ao final. `UNNEST` costuma ser usado com um `JOIN` e pode fazer referência a colunas de relações no lado esquerdo do `JOIN`. ## Obter os locais de arquivos dos dados de origem no Amazon S3 Para ver o local do arquivo do Amazon S3 referente aos dados em uma linha da tabela, você pode usar `"$path"` em uma consulta `SELECT`, como no seguinte exemplo: ``` SELECT "$path" FROM "my_database"."my_table" WHERE year=2019; ``` Essa consulta retorna um resultado semelhante a este: ``` s3://amzn-s3-demo-bucket/datasets_mytable/year=2019/data_file1.json ``` Para retornar uma lista classificada e exclusiva dos caminhos de nome de arquivo do S3 para os dados em uma tabela, você pode usar `SELECT DISTINCT` e `ORDER BY`, como no exemplo a seguir. ``` SELECT DISTINCT "$path" AS data_source_file FROM sampledb.elb_logs ORDER By data_source_file ASC ``` Para retornar somente os nomes de arquivo sem o caminho, você pode especificar `"$path"` como um parâmetro para a função `regexp_extract`, conforme mostrado no exemplo a seguir. ``` SELECT DISTINCT regexp_extract("$path", '[^/]+$') AS data_source_file FROM sampledb.elb_logs ORDER By data_source_file ASC ``` Para retornar os dados de um arquivo específico, especifique o arquivo na cláusula `WHERE`, como no exemplo a seguir. ``` SELECT *,"$path" FROM my_database.my_table WHERE "$path" = 's3://amzn-s3-demo-bucket/my_table/my_partition/file-01.csv' ``` Para obter mais informações e exemplos, consulte o artigo da Central de Conhecimento [Como posso ver o arquivo de origem do Amazon S3 para uma linha em uma tabela do Athena?](https://aws.amazon.com/premiumsupport/knowledge-center/find-s3-source-file-athena-table-row/) **nota** No Athena, as colunas ocultas de metadados do Hive ou do Iceberg `$bucket`, `$file_modified_time`, `$file_size` e `$partition` não são compatíveis para visualizações. ## Caractere de escape para aspas simples Para inserir caracteres de escape em aspas simples, preceda-as com outras aspas simples, conforme o exemplo a seguir. Não confunda isso com aspas duplas. ``` Select 'O''Reilly' ``` **Resultados** `O'Reilly` ## Recursos adicionais Para obter mais informações sobre como usaras instruções `SELECT` no Athena, consulte os recursos abaixo. | Para obter informações sobre este tópico | consulte esta referência | | --- | --- | | Executar consultas no Athena | [Executar consultas SQL no Amazon Athena](querying-athena-tables.md) | | Usar SELECT para criar uma tabela | [Criar uma tabela com base em resultados de consultas (CTAS)](ctas.md) | | Inserir dados de uma consulta SELECT em outra tabela | [INSERT INTO](insert-into.md) | | Usar funções integradas nas instruções SELECT | [Funções no Amazon Athena](functions.md) | | Usar funções definidas pelo usuário nas instruções SELECT | [Consultar com funções definidas pelo usuário](querying-udf.md) | | Consultar metadados do catálogo de dados | [Consultar o AWS Glue Data Catalog](querying-glue-catalog.md) | # INSERT INTO Insere novas linhas em uma tabela de destino com base em uma instrução de consulta `SELECT` executada em uma tabela de origem ou com base em um conjunto de `VALUES` fornecidos como parte da instrução. Quando a tabela de origem é baseada em dados subjacentes em um formato, como CSV ou JSON, e a tabela de destino é baseada em outro formato, como Parquet ou ORC, você pode usar as consultas `INSERT INTO` para transformar os dados selecionados no formato da tabela de destino. ## Considerações e limitações Considere o seguinte ao usar as consultas `INSERT` com o Athena. + Ao executar uma consulta `INSERT` em uma tabela com dados subjacentes criptografados no Amazon S3, os arquivos de saída que a consulta `INSERT` grava não são criptografados por padrão. Recomendamos que você criptografe os resultados da consulta `INSERT` se estiver inserindo em tabelas com dados criptografados. Para obter mais informações sobre como criptografar resultados da consulta usando o console, consulte [Criptografar os resultados de consultas do Athena armazenados no Amazon S3](encrypting-query-results-stored-in-s3.md). Para habilitar a criptografia usando a AWS CLI ou a API do Athena, use as propriedades `EncryptionConfiguration` da ação [StartQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html) para especificar as opções de criptografia do Amazon S3 de acordo com os seus requisitos. + Para instruções `INSERT INTO`, a configuração do proprietário do bucket esperado não se aplica ao local da tabela de destino no Amazon S3. A configuração esperada do proprietário do bucket se aplica somente ao local de saída do Amazon S3 que você especificar para os resultados da consulta do Athena. Para obter mais informações, consulte [Especificar um local para resultados de consultas com uso do console do Athena](query-results-specify-location-console.md). + Para obter instruções `INSERT INTO` em conformidade com ACID, consulte a seção `INSERT INTO` em [Atualizar dados nas tabelas do Iceberg](querying-iceberg-updating-iceberg-table-data.md). ### Formatos compatíveis e SerDes É possível executar uma consulta `INSERT` em tabelas criadas de dados com os seguintes formatos e SerDes. | Formato de dados | SerDe | | --- | --- | | Avro | org.apache.hadoop.hive.serde2.avro.AvroSerDe | | Ion | com.amazon.ionhiveserde.IonHiveSerDe | | JSON | org.apache.hive.hcatalog.data.JsonSerDe | | ORC | org.apache.hadoop.hive.ql.io.orc.OrcSerde | | Parquet | org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe | | Arquivo de texto | org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe Há suporte a arquivos TSV e delimitados personalizados. | | CSV | org.apache.hadoop.hive.serde2.OpenCSVSerde Há suporte a operações de escrita somente em tipos string. No Athena, não é possível escrever em tabelas que contêm tipos não string no esquema do Glue. Para obter mais informações, consulte [CSV SerDe](csv-serde.md#csv-serde-opencsvserde-considerations-non-string). | ### Tabelas em bucket sem suporte `INSERT INTO` não é compatível com tabelas em bucket. Para obter mais informações, consulte [Usar particionamento e bucketing](ctas-partitioning-and-bucketing.md). ### Consultas federadas sem suporte `INSERT INTO` não é suportado para consultas federadas. Tentar fazer isso pode gerar a mensagem de erro: This operation is currently not supported for external catalogs (Atualmente, esta operação não é suportada para catálogos externos). Para obter informações sobre consultas federadas, consulte [Usar a consulta federada do Amazon Athena](federated-queries.md). ### Particionamento Considere os pontos desta seção ao usar o particionamento com as consultas `INSERT INTO` ou `CREATE TABLE AS SELECT`. #### Limites A instrução `INSERT INTO` comporta a gravação de no máximo 100 combinações de partições na tabela de destino. Se você executar a cláusula `SELECT` em uma tabela com mais de 100 partições, a consulta falhará a menos que a consulta `SELECT` seja limitada a 100 partições ou menos. Para obter informações sobre como contornar essa limitação, consulte [Usar CTAS e INSERT INTO para resolver o limite de 100 partições](ctas-insert-into.md). #### Ordem das colunas As instruções `INSERT INTO` ou `CREATE TABLE AS SELECT` esperam que a coluna particionada seja a última na lista de colunas projetadas em uma instrução `SELECT`. Se a tabela de origem não for particionada ou for particionada em colunas diferentes em comparação com a tabela de destino, as consultas como `INSERT INTO destination_table SELECT * FROM source_table` vão considerar os valores na última coluna da tabela de origem como os valores de uma coluna de partição na tabela de destino. Tenha isso em mente ao tentar criar uma tabela particionada com base em uma tabela não particionada. #### Recursos Para obter mais informações sobre como usar `INSERT INTO` com particionamento, consulte os recursos abaixo. + Para inserir dados particionados em uma tabela particionada, consulte [Usar CTAS e INSERT INTO para resolver o limite de 100 partições](ctas-insert-into.md). + Para inserir dados não particionados em uma tabela particionada, consulte [Usar CTAS e INSERT INTO para ETL e análise de dados](ctas-insert-into-etl.md). ### Arquivos gravados no Amazon S3 O Athena grava arquivos nos locais dos dados de origem no Amazon S3 como resultado do comando `INSERT`. Cada operação `INSERT` cria um novo arquivo, em vez de anexar a um arquivo existente. Os locais de arquivos dependem da estrutura da tabela e da consulta `SELECT`, se houver. O Athena gera um arquivo manifesto de dados para cada consulta `INSERT`. O manifesto rastreia os arquivos que a consulta gravou. Ele é salvo no local dos resultados das consultas do Athena no Amazon S3. Para obter mais informações, consulte [Identificar arquivos de saída de consultas](querying-finding-output-files.md#querying-identifying-output-files). ### Evitar atualizações altamente transacionais Quando você usa `INSERT INTO` para adicionar linhas a uma tabela no Amazon S3, o Athena não reescreve nem modifica arquivos existentes. Em vez disso, ele grava as linhas como um ou mais novos arquivos. Como tabelas com [muitos arquivos pequenos resultam em desempenho inferior de consultas](performance-tuning-data-optimization-techniques.md#performance-tuning-avoid-having-too-many-files), e operações de gravação e leitura, como `PutObject` e `GetObject`, resultam em custos mais altos no Amazon S3, considere as seguintes opções ao usar `INSERT INTO`: + Execute operações `INSERT INTO` com menor frequência em lotes maiores de linhas. + Para grandes volumes de ingestão de dados, considere usar um serviço como o [Amazon Data Firehose](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html). + Evite completamente o uso de `INSERT INTO`. Em vez disso, acumule linhas em arquivos maiores e faça o upload deles diretamente para o Amazon S3, onde poderão ser consultados pelo Athena. ### Localizar arquivos órfãos Se uma instrução `INSERT INTO` ou `CTAS` falhar, os dados órfãos poderão ser deixados no local de dados e ser lidos em consultas subsequentes. Para localizar arquivos órfãos para inspeção ou exclusão, é possível usar o arquivo do manifesto de dados que o Athena oferece para rastrear a lista de arquivos a serem gravados. Para obter mais informações, consulte [Identificar arquivos de saída de consultas](querying-finding-output-files.md#querying-identifying-output-files) e [DataManifestLocation](https://docs.aws.amazon.com/athena/latest/APIReference/API_QueryExecutionStatistics.html#athena-Type-QueryExecutionStatistics-DataManifestLocation). ## INSERT INTO...SELECT Especifica a consulta a ser executada em uma tabela, `source_table`, que determina as linhas a serem inseridas em uma segunda tabela, `destination_table`. Se a consulta `SELECT` especificar colunas na `source_table`, as colunas deverão corresponder precisamente àquelas na `destination_table`. Para obter mais informações sobre consultas `SELECT`, consulte [SELECT](select.md). ### Resumo ``` INSERT INTO destination_table SELECT select_query FROM source_table_or_view ``` ### Exemplos Selecione todas as linhas na tabela `vancouver_pageviews` e insira-as na tabela `canada_pageviews`: ``` INSERT INTO canada_pageviews SELECT * FROM vancouver_pageviews; ``` Selecione apenas as linhas na tabela `vancouver_pageviews` em que a coluna `date` tenha um valor entre `2019-07-01` e `2019-07-31`, e insira-as em `canada_july_pageviews`: ``` INSERT INTO canada_july_pageviews SELECT * FROM vancouver_pageviews WHERE date BETWEEN date '2019-07-01' AND '2019-07-31'; ``` Selecione os valores nas colunas `city` e `state` na tabela `cities_world` somente dessas linhas com um valor `usa` na coluna `country` e insira-os nas colunas `city` e `state` na tabela `cities_usa`: ``` INSERT INTO cities_usa (city,state) SELECT city,state FROM cities_world WHERE country='usa' ``` ## INSERT INTO...VALUES Insere linhas em uma tabela existente especificando colunas e valores. As colunas especificadas e os tipos de dados associados devem corresponder precisamente às colunas e aos tipos de dados na tabela de destino. **Importante** Não recomendamos inserir linhas com `VALUES` porque o Athena gera arquivos para cada operação `INSERT`. Isso pode fazer com que muitos arquivos pequenos sejam criados e degradem a performance de consulta da tabela. Para identificar arquivos que uma consulta `INSERT` cria, examine o arquivo manifesto de dados. Para obter mais informações, consulte [Trabalhar com resultados de consultas e consultas recentes](querying.md). ### Resumo ``` INSERT INTO destination_table [(col1,col2,...)] VALUES (col1value,col2value,...)[, (col1value,col2value,...)][, ...] ``` ### Exemplos Nos exemplos a seguir, a tabela de cidades tem três colunas: `id`, `city`, `state`, `state_motto`. A coluna `id` é do tipo `INT`, e todas as outras colunas são do tipo `VARCHAR`. Insira uma única linha na tabela `cities`, com todos os valores da coluna especificados: ``` INSERT INTO cities VALUES (1,'Lansing','MI','Si quaeris peninsulam amoenam circumspice') ``` Insira duas linhas na tabela `cities`: ``` INSERT INTO cities VALUES (1,'Lansing','MI','Si quaeris peninsulam amoenam circumspice'), (3,'Boise','ID','Esto perpetua') ``` # VALUES Cria uma tabela em linha de literais. A tabela pode ser anônima ou você pode usar a cláusula `AS` para especificar um nome de tabela, nomes de colunas ou ambos. ## Resumo ``` VALUES row [, ...] ``` ## Parâmetros **linha** O parâmetro `row` pode ser uma única expressão ou `( column_expression [, ...] )`. ## Exemplos Retornar uma tabela com uma coluna e três linhas: ``` VALUES 1, 2, 3 ``` Retornar uma tabela com duas colunas e três linhas: ``` VALUES (1, 'a'), (2, 'b'), (3, 'c') ``` Retornar uma tabela com as colunas `id` e `name`: ``` SELECT * FROM ( VALUES (1, 'a'), (2, 'b'), (3, 'c') ) AS t (id, name) ``` Criar uma tabela denominada `customers` com as colunas `id` e `name`: ``` CREATE TABLE customers AS SELECT * FROM ( VALUES (1, 'a'), (2, 'b'), (3, 'c') ) AS t (id, name) ``` ## Consulte também [INSERT INTO...VALUES](insert-into.md#insert-into-values) # DELETE Exclui linhas em uma tabela do Apache Iceberg. `DELETE` é transacional e é compatível somente com tabelas do Apache Iceberg. ## Resumo Para excluir as linhas de uma tabela do Iceberg, use a sintaxe a seguir. ``` DELETE FROM [db_name.]table_name [WHERE predicate] ``` Para obter mais informações e exemplos, consulte a seção `DELETE` da [Atualizar dados nas tabelas do Iceberg](querying-iceberg-updating-iceberg-table-data.md). # UPDATE Atualiza linhas em uma tabela do Apache Iceberg. `UPDATE` é transacional e é compatível somente com tabelas do Apache Iceberg. A instrução funciona somente em linhas existentes e não pode ser usada para inserir ou acrescentar uma linha. ## Resumo Para atualizar as linhas em uma tabela do Iceberg, use a sintaxe a seguir. ``` UPDATE [db_name.]table_name SET xx=yy[,...] [WHERE predicate] ``` Para obter mais informações e exemplos, consulte a seção `UPDATE` da [Atualizar dados nas tabelas do Iceberg](querying-iceberg-updating-iceberg-table-data.md). # MERGE INTO Atualiza, exclui ou insere linhas de forma condicional em uma tabela do Apache Iceberg. Uma única instrução pode combinar ações de atualização, exclusão e inserção. **nota** `MERGE INTO` é transacional e é compatível somente com tabelas do Apache Iceberg na versão 3 do mecanismo do Athena. ## Resumo Para atualizar, excluir ou inserir linhas de forma condicional em uma tabela do Iceberg, use a sintaxe a seguir. ``` MERGE INTO target_table [ [ AS ] target_alias ] USING { source_table | query } [ [ AS ] source_alias ] ON search_condition when_clause [...] ``` A *when\$1clause* corresponde a uma das seguintes: ``` WHEN MATCHED [ AND condition ] THEN DELETE ``` ``` WHEN MATCHED [ AND condition ] THEN UPDATE SET ( column = expression [, ...] ) ``` ``` WHEN NOT MATCHED [ AND condition ] THEN INSERT (column_name[, column_name ...]) VALUES (expression, ...) ``` `MERGE` é compatível com um número arbitrário de cláusulas `WHEN` com diferentes condições `MATCHED`. As cláusulas de condição executam as operações `DELETE`, `UPDATE` ou `INSERT` na primeira cláusula `WHEN` selecionada pelo estado `MATCHED` e pela condição de correspondência. Para cada linha de origem, as cláusulas `WHEN` são processadas por ordem. Somente a primeira cláusula `WHEN` correspondente é executada. As cláusulas subsequentes são ignoradas. Um erro de usuário é gerado quando uma única linha da tabela de destino corresponde a mais de uma linha de origem. Se uma linha de origem não corresponder a nenhuma cláusula `WHEN` e não houver uma cláusula `WHEN NOT MATCHED`, a linha de origem será ignorada. Nas cláusulas `WHEN` que têm operações `UPDATE`, as expressões de valor da coluna podem se referir a qualquer campo de destino ou de origem. No caso de `NOT MATCHED`, as expressões `INSERT` podem se referir a qualquer campo de origem. **Exemplo** O exemplo a seguir mescla linhas da segunda tabela com a primeira tabela, se as linhas não existirem na primeira tabela. As colunas listadas na cláusula `VALUES` devem ser prefixadas pelo alias da tabela de origem. As colunas de destino listadas na cláusula `INSERT` *não* devem ter esse prefixo. ``` MERGE INTO iceberg_table_sample as ice1 USING iceberg2_table_sample as ice2 ON ice1.col1 = ice2.col1 WHEN NOT MATCHED THEN INSERT (col1) VALUES (ice2.col1) ``` Para obter mais exemplos de `MERGE INTO`, consulte [Atualizar dados nas tabelas do Iceberg](querying-iceberg-updating-iceberg-table-data.md). # OPTIMIZE Otimize as linhas em uma tabela do Apache Iceberg ao gravar novamente arquivos de dados em um layout mais otimizado com base em no tamanho e no número de arquivos excluídos associados. **nota** `OPTIMIZE` é transacional e é compatível somente para tabelas do Apache Iceberg. ## Sintaxe O resumo da sintaxe a seguir mostra como otimizar o layout de dados para uma tabela Iceberg. ``` OPTIMIZE [db_name.]table_name REWRITE DATA USING BIN_PACK [WHERE predicate] ``` **nota** Somente colunas de partição são permitidas no *predicado* da cláusula `WHERE`. Especificar uma coluna sem partição fará com que a consulta falhe. A ação de compactação é cobrada pela quantidade de dados verificados durante o processo de regravação. A ação `REWRITE DATA` usa predicados para selecionar arquivos que contenham linhas iguais. Se alguma linha no arquivo corresponder ao predicado, o arquivo será selecionado para otimização. Assim, para controlar o número de arquivos afetados pela operação de compactação, você pode especificar uma cláusula `WHERE`. ## Configurar propriedades de compactação Para controlar o tamanho dos arquivos a serem selecionados para compactação e o tamanho do arquivo resultante após a compactação, você pode usar parâmetros de propriedade de tabela. Você pode usar o comando [ALTER TABLE SET TBLPROPERTIES](querying-iceberg-alter-table-set-properties.md) para configurar as [propriedades de tabela](querying-iceberg-creating-tables.md#querying-iceberg-table-properties) a seguir. ## Recursos adicionais [Otimizar tabelas do Iceberg](querying-iceberg-data-optimization.md) # VACUUM A instrução `VACUUM` realiza a manutenção da tabela para as tabelas do Apache Iceberg ao realizar a [expiração de snapshots](https://iceberg.apache.org/docs/latest/spark-procedures/#expire_snapshots) e a [remoção do arquivo órfão](https://iceberg.apache.org/docs/latest/spark-procedures/#remove_orphan_files). **nota** `VACUUM` é transacional e é compatível somente com tabelas do Apache Iceberg na versão 3 do mecanismo do Athena. A instrução `VACUUM` otimiza as tabelas do Iceberg ao reduzir o consumo de armazenamento. Para obter mais informações sobre o uso de `VACUUM`, consulte [Otimizar tabelas do Iceberg](querying-iceberg-data-optimization.md). Como a instrução `VACUUM` faz chamadas de API para o Amazon S3, as cobranças se aplicam às solicitações associadas ao Amazon S3. **Atenção** Se você executar uma operação de expiração de snapshot, não poderá mais fazer viagens no tempo para snapshots expirados. ## Resumo Para remover os arquivos de dados que não são mais necessários para uma tabela do Iceberg, use a sintaxe a seguir. ``` VACUUM [database_name.]target_table ``` + O `VACUUM` espera que os dados do Iceberg estejam em uma pasta do Amazon S3 em vez de em um bucket do Amazon S3. Por exemplo, se seus dados do Iceberg estiverem em `s3://amzn-s3-demo-bucket`/ em vez de `s3://amzn-s3-demo-bucket/myicebergfolder/`, a instrução `VACUUM` falhará com a mensagem de erro GENERIC\$1INTERNAL\$1ERROR: Path missing in file system location: `s3://amzn-s3-demo-bucket`. + Para que o `VACUUM` possa excluir arquivos de dados, sua função de execução de consulta deve ter as permissões `s3:DeleteObject` no bucket em que suas tabelas, metadados, snapshots e arquivos de dados do Iceberg estão localizados. Se a permissão não estiver presente, a consulta de `VACUUM` será bem-sucedida, mas os arquivos não serão excluídos. + Para executar `VACUUM` em uma tabela com um nome que comece com um sublinhado (por exemplo, `_mytable`), coloque o nome da tabela entre acentos maiúsculos, como no exemplo a seguir. Se você prefixar o nome da tabela com um nome de banco de dados, não coloque o nome do banco de dados entre aspas. Observe que aspas duplas não funcionarão no lugar dos acentos. Esse comportamento é específico do `VACUUM`. As instruções `CREATE` e `INSERT INTO` não exigem acentos graves para nomes de tabelas que começam com sublinhados. ``` VACUUM `_mytable` VACUUM my_database.`_mytable` ``` ## Operações realizadas `VACUUM` realiza as seguintes operações: + Remove os snapshots que são mais antigos do que o tempo especificado pela propriedade de tabela `vacuum_max_snapshot_age_seconds`. Por padrão, essa propriedade é definida para 432 mil segundos (cinco dias). + Remove os snapshots que não estão dentro do período de retenção e que excedem o número especificado pela propriedade de tabela `vacuum_min_snapshots_to_keep`. O padrão é um. É possível especificar essas propriedades de tabela em sua instrução `CREATE TABLE`. Após a criação da tabela, é possível usar a instrução [ALTER TABLE SET TBLPROPERTIES](querying-iceberg-alter-table-set-properties.md) para atualizá-la. + Remove todos os metadados e os arquivos de dados inacessíveis como resultado da remoção do snapshot. Você pode configurar o número de arquivos de metadados antigos a serem retidos definindo a propriedade da tabela `vacuum_max_metadata_files_to_keep`. O valor padrão é 100. + Remove arquivos órfãos que são mais antigos do que o tempo especificado na propriedade de tabela `vacuum_max_snapshot_age_seconds`. Arquivos órfãos corresponde a arquivos no diretório de dados da tabela que não fazem parte do estado da tabela. Para obter mais informações sobre como criar e gerenciar tabelas do Apache Iceberg no Athena, consulte [Criar tabelas do Iceberg](querying-iceberg-creating-tables.md) e [Gerenciar tabelas do Iceberg](querying-iceberg-managing-tables.md). # Usar EXPLAIN e EXPLAIN ANALYZE no Athena A instrução `EXPLAIN` mostra o plano de execução lógico ou distribuído de uma instrução SQL especificada ou valida a instrução SQL. Você pode gerar os resultados no formato de texto ou em um formato de dados para renderização em gráfico. **nota** É possível visualizar representações gráficas de planos lógicos e distribuídos para suas consultas no console do Athena sem usar a sintaxe `EXPLAIN`. Para obter mais informações, consulte [Visualização de planos de execução para consultas SQL](query-plans.md). O `EXPLAIN ANALYZE` mostra o plano de execução distribuído de uma instrução SQL especificada e o custo computacional de cada operação em uma consulta SQL. Você pode gerar os resultados no formato de texto ou JSON. ## Considerações e limitações As instruções `EXPLAIN` e `EXPLAIN ANALYZE` no Athena têm as limitações a seguir. + Como as consultas `EXPLAIN` não verificam os dados, o Athena não cobra por elas. Entretanto, como as consultas `EXPLAIN` fazem chamadas ao AWS Glue para recuperar metadados de tabela, poderá haver cobranças do Glue se as chamadas ultrapassarem o [limite do nível gratuito do Glue](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Categories=categories%23analytics&all-free-tier.q=glue&all-free-tier.q_operator=AND). + Como consultas `EXPLAIN ANALYZE` são executadas, elas verificam os dados, e o Athena cobra pela quantidade de dados verificados. + As informações de filtragem de linha ou de célula definidas no Lake Formation e as informações de estatísticas de consulta não são mostradas na saída de `EXPLAIN` e de `EXPLAIN ANALYZE`. ## Sintaxe de EXPLAIN ``` EXPLAIN [ ( option [, ...]) ] statement ``` *opção* pode ser uma das seguintes: ``` FORMAT { TEXT | GRAPHVIZ | JSON } TYPE { LOGICAL | DISTRIBUTED | VALIDATE | IO } ``` Se a opção `FORMAT` não for especificada, o padrão de saída será o formato `TEXT`. O tipo`IO` fornece informações sobre as tabelas e os esquemas lidos pela consulta. ## Sintaxe de EXPLAIN ANALYZE Além da saída incluída em `EXPLAIN`, a saída de `EXPLAIN ANALYZE` também inclui estatísticas de runtime para a consulta especificada, como o uso da CPU, o número de linhas da entrada e o número de linhas da saída. ``` EXPLAIN ANALYZE [ ( option [, ...]) ] statement ``` *opção* pode ser uma das seguintes: ``` FORMAT { TEXT | JSON } ``` Se a opção `FORMAT` não for especificada, o padrão de saída será o formato `TEXT`. Porque todas as consultas para `EXPLAIN ANALYZE` são `DISTRIBUTED`, a opção `TYPE` não está disponível para `EXPLAIN ANALYZE`. A *instrução* pode ser uma das seguintes: ``` SELECT CREATE TABLE AS SELECT INSERT UNLOAD ``` ## Exemplos de EXPLAIN Os exemplos a seguir representam a progressão de `EXPLAIN`, do mais simples ao mais complexo. ### Exemplo 1: uso da a instrução EXPLAIN para mostrar um plano de consulta no formato de texto No exemplo a seguir, `EXPLAIN` mostra o plano de execução de uma consulta `SELECT` nos logs do Elastic Load Balancing. O formato é o padrão para saída de texto. ``` EXPLAIN SELECT request_timestamp, elb_name, request_ip FROM sampledb.elb_logs; ``` #### Resultados ``` - Output[request_timestamp, elb_name, request_ip] => [[request_timestamp, elb_name, request_ip]] - RemoteExchange[GATHER] => [[request_timestamp, elb_name, request_ip]] - TableScan[awsdatacatalog:HiveTableHandle{schemaName=sampledb, tableName=elb_logs, analyzePartitionValues=Optional.empty}] => [[request_timestamp, elb_name, request_ip]] LAYOUT: sampledb.elb_logs request_ip := request_ip:string:2:REGULAR request_timestamp := request_timestamp:string:0:REGULAR elb_name := elb_name:string:1:REGULAR ``` ### Exemplo 2: uso de EXPLAIN para representar um plano de consulta graficamente É possível utilizar o console do Athena para representar um plano de consulta graficamente para você. Insira uma instrução `SELECT` como a seguinte no editor de consultas do Athena e escolha **EXPLAIN**. ``` SELECT c.c_custkey, o.o_orderkey, o.o_orderstatus FROM tpch100.customer c JOIN tpch100.orders o ON c.c_custkey = o.o_custkey ``` A página **Explain** (Explicar) do editor de consultas do Athena é aberta e mostra um plano distribuído e um plano lógico para a consulta. O gráfico a seguir mostra o plano lógico do exemplo. ![\[Gráfico do plano de consulta renderizado pelo editor de consulta do Athena.\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/images/athena-explain-statement-tpch.png) **Importante** Alguns filtros de partição podem não estar visíveis no gráfico de árvore do operador aninhado, mesmo que o Athena os aplique à sua consulta. Para verificar o efeito desses filtros, execute `EXPLAIN` ou `EXPLAIN ANALYZE` na sua consulta e visualize os resultados. Para obter mais informações sobre como usar os recursos de gráfico do plano de consulta no console do Athena, consulte [Visualização de planos de execução para consultas SQL](query-plans.md). ### Exemplo 3: uso da instrução EXPLAIN para verificar redução da partição Quando você usa um predicado de filtragem em uma chave particionada para consultar uma tabela particionada, o mecanismo de consulta aplica o predicado à chave particionada para reduzir a quantidade de dados lidos. O exemplo a seguir usa uma consulta `EXPLAIN` para verificar a remoção da partição de uma consulta `SELECT` em uma tabela particionada. Primeiro, a instrução `CREATE TABLE` cria a tabela `tpch100.orders_partitioned`. A tabela é particionada na coluna `o_orderdate`. ``` CREATE TABLE `tpch100.orders_partitioned`( `o_orderkey` int, `o_custkey` int, `o_orderstatus` string, `o_totalprice` double, `o_orderpriority` string, `o_clerk` string, `o_shippriority` int, `o_comment` string) PARTITIONED BY ( `o_orderdate` string) ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe' STORED AS INPUTFORMAT 'org.apache.hadoop.hive.ql.io.parquet.MapredParquetInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.parquet.MapredParquetOutputFormat' LOCATION 's3://amzn-s3-demo-bucket//' ``` A tabela `tpch100.orders_partitioned` tem várias partições em `o_orderdate`, como mostrado pelo comando `SHOW PARTITIONS`. ``` SHOW PARTITIONS tpch100.orders_partitioned; o_orderdate=1994 o_orderdate=2015 o_orderdate=1998 o_orderdate=1995 o_orderdate=1993 o_orderdate=1997 o_orderdate=1992 o_orderdate=1996 ``` A consulta `EXPLAIN` a seguir verifica a remoção da partição com base na instrução `SELECT` especificada. ``` EXPLAIN SELECT o_orderkey, o_custkey, o_orderdate FROM tpch100.orders_partitioned WHERE o_orderdate = '1995' ``` #### Resultados ``` Query Plan - Output[o_orderkey, o_custkey, o_orderdate] => [[o_orderkey, o_custkey, o_orderdate]] - RemoteExchange[GATHER] => [[o_orderkey, o_custkey, o_orderdate]] - TableScan[awsdatacatalog:HiveTableHandle{schemaName=tpch100, tableName=orders_partitioned, analyzePartitionValues=Optional.empty}] => [[o_orderkey, o_custkey, o_orderdate]] LAYOUT: tpch100.orders_partitioned o_orderdate := o_orderdate:string:-1:PARTITION_KEY :: [[1995]] o_custkey := o_custkey:int:1:REGULAR o_orderkey := o_orderkey:int:0:REGULAR ``` O texto em negrito no resultado mostra que o predicado `o_orderdate = '1995'` foi aplicado a `PARTITION_KEY`. ### Exemplo 4: uso de uma consulta EXPLAIN para verificar ordem e tipo de junção A consulta `EXPLAIN` a seguir verifica o tipo e a ordem de junção da instrução `SELECT`. Use uma consulta como esta para examinar o uso da memória de consulta para que você possa reduzir as chances de receber um erro `EXCEEDED_LOCAL_MEMORY_LIMIT`. ``` EXPLAIN (TYPE DISTRIBUTED) SELECT c.c_custkey, o.o_orderkey, o.o_orderstatus FROM tpch100.customer c JOIN tpch100.orders o ON c.c_custkey = o.o_custkey WHERE c.c_custkey = 123 ``` #### Resultados ``` Query Plan Fragment 0 [SINGLE] Output layout: [c_custkey, o_orderkey, o_orderstatus] Output partitioning: SINGLE [] Stage Execution Strategy: UNGROUPED_EXECUTION - Output[c_custkey, o_orderkey, o_orderstatus] => [[c_custkey, o_orderkey, o_orderstatus]] - RemoteSource[1] => [[c_custkey, o_orderstatus, o_orderkey]] Fragment 1 [SOURCE] Output layout: [c_custkey, o_orderstatus, o_orderkey] Output partitioning: SINGLE [] Stage Execution Strategy: UNGROUPED_EXECUTION - CrossJoin => [[c_custkey, o_orderstatus, o_orderkey]] Distribution: REPLICATED - ScanFilter[table = awsdatacatalog:HiveTableHandle{schemaName=tpch100, tableName=customer, analyzePartitionValues=Optional.empty}, grouped = false, filterPredicate = ("c_custkey" = 123)] => [[c_custkey]] LAYOUT: tpch100.customer c_custkey := c_custkey:int:0:REGULAR - LocalExchange[SINGLE] () => [[o_orderstatus, o_orderkey]] - RemoteSource[2] => [[o_orderstatus, o_orderkey]] Fragment 2 [SOURCE] Output layout: [o_orderstatus, o_orderkey] Output partitioning: BROADCAST [] Stage Execution Strategy: UNGROUPED_EXECUTION - ScanFilterProject[table = awsdatacatalog:HiveTableHandle{schemaName=tpch100, tableName=orders, analyzePartitionValues=Optional.empty}, grouped = false, filterPredicate = ("o_custkey" = 123)] => [[o_orderstatus, o_orderkey]] LAYOUT: tpch100.orders o_orderstatus := o_orderstatus:string:2:REGULAR o_custkey := o_custkey:int:1:REGULAR o_orderkey := o_orderkey:int:0:REGULAR ``` A consulta de exemplo foi otimizada em uma junção cruzada para uma performance melhor. Os resultados mostram que `tpch100.orders` será distribuído como o tipo de distribuição `BROADCAST`. Isso indica que a tabela `tpch100.orders` será distribuída para todos os nós que executam a operação de junção. O tipo de distribuição `BROADCAST` exige que todos os resultados filtrados da tabela `tpch100.orders` estejam dentro da capacidade de memória de cada nó que executa a operação de junção. No entanto, a tabela `tpch100.customer` é menor que `tpch100.orders`. Como `tpch100.customer` requer menos memória, você pode reescrever a consulta como `BROADCAST tpch100.customer` em vez de `tpch100.orders`. Desse modo, a consulta tem menos chance de receber o erro `EXCEEDED_LOCAL_MEMORY_LIMIT`. Essa estratégia considera os seguintes pontos: + `tpch100.customer.c_custkey` é exclusivo na tabela `tpch100.customer`. + Existe um relacionamento de mapeamento um para muitos entre `tpch100.customer` e `tpch100.orders`. O exemplo a seguir mostra a consulta reescrita. ``` SELECT c.c_custkey, o.o_orderkey, o.o_orderstatus FROM tpch100.orders o JOIN tpch100.customer c -- the filtered results of tpch100.customer are distributed to all nodes. ON c.c_custkey = o.o_custkey WHERE c.c_custkey = 123 ``` ### Exemplo 5: uso de uma consulta EXPLAIN para remover predicados sem efeito Você pode usar uma consulta `EXPLAIN` para verificar a eficácia dos predicados de filtragem. Você pode usar os resultados para remover os predicados que não têm efeito, como no exemplo a seguir. ``` EXPLAIN SELECT c.c_name FROM tpch100.customer c WHERE c.c_custkey = CAST(RANDOM() * 1000 AS INT) AND c.c_custkey BETWEEN 1000 AND 2000 AND c.c_custkey = 1500 ``` #### Resultados ``` Query Plan - Output[c_name] => [[c_name]] - RemoteExchange[GATHER] => [[c_name]] - ScanFilterProject[table = awsdatacatalog:HiveTableHandle{schemaName=tpch100, tableName=customer, analyzePartitionValues=Optional.empty}, filterPredicate = (("c_custkey" = 1500) AND ("c_custkey" = CAST(("random"() * 1E3) AS int)))] => [[c_name]] LAYOUT: tpch100.customer c_custkey := c_custkey:int:0:REGULAR c_name := c_name:string:1:REGULAR ``` O `filterPredicate` nos resultados mostra que o otimizador mesclou os três predicados originais em dois predicados e alterou a ordem de aplicação deles. ``` filterPredicate = (("c_custkey" = 1500) AND ("c_custkey" = CAST(("random"() * 1E3) AS int))) ``` Como os resultados mostram que o predicado `AND c.c_custkey BETWEEN 1000 AND 2000` não tem efeito, você pode removê-lo sem alterar os resultados da consulta. Para obter informações sobre os termos usados nos resultados das consultas `EXPLAIN`, veja [Noções básicas dos resultados da instrução EXPLAIN do Athena](athena-explain-statement-understanding.md). ## Exemplos de EXPLAIN ANALYZE Os exemplos a seguir mostram exemplos de consultas e saídas de `EXPLAIN ANALYZE`. ### Exemplo 1: uso de EXPLAIN ANALYZE para mostrar um plano de consulta e o custo computacional em formato de texto No exemplo a seguir, `EXPLAIN ANALYZE` mostra o plano de execução e os custos computacionais de uma consulta `SELECT` em logs do CloudFront. O formato é o padrão para saída de texto. ``` EXPLAIN ANALYZE SELECT FROM cloudfront_logs LIMIT 10 ``` #### Resultados ``` Fragment 1 CPU: 24.60ms, Input: 10 rows (1.48kB); per task: std.dev.: 0.00, Output: 10 rows (1.48kB) Output layout: [date, time, location, bytes, requestip, method, host, uri, status, referrer,\ os, browser, browserversion] Limit[10] => [[date, time, location, bytes, requestip, method, host, uri, status, referrer, os,\ browser, browserversion]] CPU: 1.00ms (0.03%), Output: 10 rows (1.48kB) Input avg.: 10.00 rows, Input std.dev.: 0.00% LocalExchange[SINGLE] () => [[date, time, location, bytes, requestip, method, host, uri, status, referrer, os,\ browser, browserversion]] CPU: 0.00ns (0.00%), Output: 10 rows (1.48kB) Input avg.: 0.63 rows, Input std.dev.: 387.30% RemoteSource[2] => [[date, time, location, bytes, requestip, method, host, uri, status, referrer, os,\ browser, browserversion]] CPU: 1.00ms (0.03%), Output: 10 rows (1.48kB) Input avg.: 0.63 rows, Input std.dev.: 387.30% Fragment 2 CPU: 3.83s, Input: 998 rows (147.21kB); per task: std.dev.: 0.00, Output: 20 rows (2.95kB) Output layout: [date, time, location, bytes, requestip, method, host, uri, status, referrer, os,\ browser, browserversion] LimitPartial[10] => [[date, time, location, bytes, requestip, method, host, uri, status, referrer, os,\ browser, browserversion]] CPU: 5.00ms (0.13%), Output: 20 rows (2.95kB) Input avg.: 166.33 rows, Input std.dev.: 141.42% TableScan[awsdatacatalog:HiveTableHandle{schemaName=default, tableName=cloudfront_logs,\ analyzePartitionValues=Optional.empty}, grouped = false] => [[date, time, location, bytes, requestip, method, host, uri, st CPU: 3.82s (99.82%), Output: 998 rows (147.21kB) Input avg.: 166.33 rows, Input std.dev.: 141.42% LAYOUT: default.cloudfront_logs date := date:date:0:REGULAR referrer := referrer:string:9:REGULAR os := os:string:10:REGULAR method := method:string:5:REGULAR bytes := bytes:int:3:REGULAR browser := browser:string:11:REGULAR host := host:string:6:REGULAR requestip := requestip:string:4:REGULAR location := location:string:2:REGULAR time := time:string:1:REGULAR uri := uri:string:7:REGULAR browserversion := browserversion:string:12:REGULAR status := status:int:8:REGULAR ``` ### Exemplo 2: uso de EXPLAIN ANALYZE para mostrar um plano de consulta em formato JSON O exemplo a seguir mostra o plano de execução e os custos computacionais de uma consulta `SELECT` em logs do CloudFront. O exemplo especifica JSON como formato de saída. ``` EXPLAIN ANALYZE (FORMAT JSON) SELECT * FROM cloudfront_logs LIMIT 10 ``` #### Resultados ``` { "fragments": [{ "id": "1", "stageStats": { "totalCpuTime": "3.31ms", "inputRows": "10 rows", "inputDataSize": "1514B", "stdDevInputRows": "0.00", "outputRows": "10 rows", "outputDataSize": "1514B" }, "outputLayout": "date, time, location, bytes, requestip, method, host,\ uri, status, referrer, os, browser, browserversion", "logicalPlan": { "1": [{ "name": "Limit", "identifier": "[10]", "outputs": ["date", "time", "location", "bytes", "requestip", "method", "host",\ "uri", "status", "referrer", "os", "browser", "browserversion"], "details": "", "distributedNodeStats": { "nodeCpuTime": "0.00ns", "nodeOutputRows": 10, "nodeOutputDataSize": "1514B", "operatorInputRowsStats": [{ "nodeInputRows": 10.0, "nodeInputRowsStdDev": 0.0 }] }, "children": [{ "name": "LocalExchange", "identifier": "[SINGLE] ()", "outputs": ["date", "time", "location", "bytes", "requestip", "method", "host",\ "uri", "status", "referrer", "os", "browser", "browserversion"], "details": "", "distributedNodeStats": { "nodeCpuTime": "0.00ns", "nodeOutputRows": 10, "nodeOutputDataSize": "1514B", "operatorInputRowsStats": [{ "nodeInputRows": 0.625, "nodeInputRowsStdDev": 387.2983346207417 }] }, "children": [{ "name": "RemoteSource", "identifier": "[2]", "outputs": ["date", "time", "location", "bytes", "requestip", "method", "host",\ "uri", "status", "referrer", "os", "browser", "browserversion"], "details": "", "distributedNodeStats": { "nodeCpuTime": "0.00ns", "nodeOutputRows": 10, "nodeOutputDataSize": "1514B", "operatorInputRowsStats": [{ "nodeInputRows": 0.625, "nodeInputRowsStdDev": 387.2983346207417 }] }, "children": [] }] }] }] } }, { "id": "2", "stageStats": { "totalCpuTime": "1.62s", "inputRows": "500 rows", "inputDataSize": "75564B", "stdDevInputRows": "0.00", "outputRows": "10 rows", "outputDataSize": "1514B" }, "outputLayout": "date, time, location, bytes, requestip, method, host, uri, status,\ referrer, os, browser, browserversion", "logicalPlan": { "1": [{ "name": "LimitPartial", "identifier": "[10]", "outputs": ["date", "time", "location", "bytes", "requestip", "method", "host", "uri",\ "status", "referrer", "os", "browser", "browserversion"], "details": "", "distributedNodeStats": { "nodeCpuTime": "0.00ns", "nodeOutputRows": 10, "nodeOutputDataSize": "1514B", "operatorInputRowsStats": [{ "nodeInputRows": 83.33333333333333, "nodeInputRowsStdDev": 223.60679774997897 }] }, "children": [{ "name": "TableScan", "identifier": "[awsdatacatalog:HiveTableHandle{schemaName=default,\ tableName=cloudfront_logs, analyzePartitionValues=Optional.empty},\ grouped = false]", "outputs": ["date", "time", "location", "bytes", "requestip", "method", "host", "uri",\ "status", "referrer", "os", "browser", "browserversion"], "details": "LAYOUT: default.cloudfront_logs\ndate := date:date:0:REGULAR\nreferrer :=\ referrer: string:9:REGULAR\nos := os:string:10:REGULAR\nmethod := method:string:5:\ REGULAR\nbytes := bytes:int:3:REGULAR\nbrowser := browser:string:11:REGULAR\nhost :=\ host:string:6:REGULAR\nrequestip := requestip:string:4:REGULAR\nlocation :=\ location:string:2:REGULAR\ntime := time:string:1: REGULAR\nuri := uri:string:7:\ REGULAR\nbrowserversion := browserversion:string:12:REGULAR\nstatus :=\ status:int:8:REGULAR\n", "distributedNodeStats": { "nodeCpuTime": "1.62s", "nodeOutputRows": 500, "nodeOutputDataSize": "75564B", "operatorInputRowsStats": [{ "nodeInputRows": 83.33333333333333, "nodeInputRowsStdDev": 223.60679774997897 }] }, "children": [] }] }] } }] } ``` ## Recursos adicionais Para obter mais informações, consulte os recursos a seguir. + [Noções básicas dos resultados da instrução EXPLAIN do Athena](athena-explain-statement-understanding.md) + [Visualização de planos de execução para consultas SQL](query-plans.md) + [Visualizar estatísticas e detalhes de execução para consultas concluídas](query-stats.md) + Documentação Trino [https://trino.io/docs/current/sql/explain.html](https://trino.io/docs/current/sql/explain.html) + Documentação Trino [https://trino.io/docs/current/sql/explain-analyze.html](https://trino.io/docs/current/sql/explain-analyze.html) + [Otimize o desempenho de consultas federadas usando EXPLAIN e EXPLAIN ANALYZE no Amazon Athena](https://aws.amazon.com/blogs/big-data/optimize-federated-query-performance-using-explain-and-explain-analyze-in-amazon-athena/) no *Blog de Big Data da AWS*. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/7JUyTqglmNU/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/7JUyTqglmNU) # Noções básicas dos resultados da instrução EXPLAIN do Athena Esse tópico apresenta uma rápida orientação sobre os termos operacionais usados nos resultados da instrução `EXPLAIN` do Athena. ## Tipos de saída da instrução EXPLAIN `EXPLAIN`As saídas da instrução podem ser de um destes dois tipos: + **Plano lógico**: mostra o plano lógico que o mecanismo SQL usa para executar uma instrução. A sintaxe para essa opção é `EXPLAIN` ou `EXPLAIN (TYPE LOGICAL)`. + **Plano distribuído**: mostra um plano de execução em um ambiente distribuído. A saída mostra fragmentos, que são os estágios de processamento. Cada fragmento do plano é processado por um ou mais nós. Os dados podem ser trocados entre os nós que processam os fragmentos. A sintaxe para essa opção é `EXPLAIN (TYPE DISTRIBUTED)`. Na saída de um plano de distribuição, os fragmentos (estágios de processamento) são indicados por `Fragment` *número* [*fragment\$1type*], em que *número* é um número inteiro com base zero e *fragment\$1type* especifica como o fragmento é executado pelos nós. Os tipos de fragmento, que mostram insights do layout da troca de dados, estão descritos na tabela a seguir. **Tipos de fragmento do plano distribuído** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/athena-explain-statement-understanding.html) ## Exchange Os termos relacionados à troca descrevem como os dados são trocados entre os nós de processamento. As transferências podem ser locais ou remotas. **LocalExchange [*exchange\$1type*] ** Transfere os dados localmente nos nós de processamento para estágios diferentes de uma consulta. O valor de *exchange\$1type* pode ser um dos tipos de troca lógicos ou distribuídos, conforme descrito mais adiante nesta seção. **RemoteExchange [*exchange\$1type*] ** Transfere os dados entre os nós de processamento para estágios diferentes de uma consulta. O valor de *exchange\$1type* pode ser um dos tipos de troca lógicos ou distribuídos, conforme descrito mais adiante nesta seção. ### Tipos de troca lógicos Os tipos de troca a seguir descrevem as ações executadas durante a fase de troca de um plano lógico. + **`GATHER`** – um único nó de processamento combina a saída de todos os outros nós de processamento. Por exemplo, o último estágio de uma consulta selecionada coleta os resultados de todos os nós e grava esses resultados no Amazon S3. + **`REPARTITION`** – envia os dados da linha para um operador específico com base no esquema de particionamento que deverá ser aplicado ao próximo operador. + **`REPLICATE`** – copia os dados da linha para todos os operadores. ### Tipos de troca distribuídos Os tipos de troca a seguir indicam o layout dos dados quando eles são trocados entre os nós em um plano distribuído. + **`HASH`** – a troca distribui os dados para vários destinos usando uma função hash. + **`SINGLE`** – a troca distribui os dados para um único destino. ## Verificação Os termos a seguir descrevem como os dados são verificados durante uma consulta. **TableScan ** Verifica os dados de origem de uma tabela do Amazon S3 ou de um conector do Apache Hive e aplica a remoção de partição gerada do predicado de filtro. **ScanFilter ** Verifica os dados de origem de uma tabela do Amazon S3 ou de um conector do Hive e aplica a remoção de partição gerada do predicado de filtro e dos outros predicados de filtro não aplicados por meio da remoção de partição. **ScanFilterProject ** Primeiramente, verifica os dados de origem de uma tabela do Amazon S3 ou de um conector do Hive e aplica a remoção de partição gerada do predicado de filtro e dos outros predicados de filtro não aplicados por meio da remoção de partição. Na sequência, modifica o layout da memória dos dados de saída para uma nova projeção a fim de melhorar a performance dos estágios posteriores. ## Ingressar Faz a junção dos dados entre duas tabelas. É possível categorizar as junções por tipo de junção e por tipo de distribuição. ### Tipos de junção Os tipos de junção definem como é feita a operação de junção. **CrossJoin**: gera o produto cartesiano de duas tabelas unidas. **InnerJoin**: seleciona os registros que têm valores correspondentes nas duas tabelas. **LeftJoin**: seleciona todos os registros da tabela esquerda e os registros correspondentes da tabela direita. Se não houver nenhuma correspondência, o resultado no lado direito será NULL. **RightJoin**: seleciona todos os registros da tabela direita e os registros correspondentes da tabela esquerda. Se não houver nenhuma correspondência, o resultado no lado direito será NULL. **FullJoin**: seleciona todos os registros em que há correspondência com os registros da tabela esquerda ou direita. A tabela unida contém todos os registros das duas tabelas e preenche as correspondências ausentes com NULL em um dos lados. **nota** Por motivos de performance, o mecanismo de consulta pode reescrever uma consulta de junção com um tipo de junção diferente para retornar os mesmos resultados. Por exemplo, uma consulta de junção interna com predicado em uma tabela pode ser reescrita como `CrossJoin`. Isso leva o predicado à fase de verificação da tabela para que menos dados sejam verificados. ### Tipos de distribuição de junção Os tipos de distribuição definem como os dados são trocados entre os nós de processamento quando a operação de junção é executada. **Particionada**: as tabelas tanto esquerda quanto direita são particionadas por hash em todos os nós de processamento. A distribuição particionada consome menos memória em cada nó. A distribuição particionada pode ser muito mais lenta do que as junções replicadas. As junções particionadas são ideais para unir duas tabelas grandes. **Replicada**: uma tabela é particionada por hash em todos os nós de processamento, e a outra tabela é replicada para todos os nós de processamento para executar a operação de junção. A distribuição replicada pode ser muito mais rápida do que as junções particionadas, mas consome mais memória em cada nó de processamento. Se a tabela replicada for muito grande, o nó de processamento poderá receber um erro de memória insuficiente. As junções replicadas são ideais quando uma das tabelas unidas é pequena. # PREPARE Cria uma instrução SQL com o nome `statement_name` para execução posterior. A instrução pode incluir parâmetros representados por pontos de interrogação. Para fornecer valores para os parâmetros e executar a instrução preparada, utilize [EXECUTE](sql-execute.md). ## Resumo ``` PREPARE statement_name FROM statement ``` A tabela a seguir descreve os parâmetros. **** | Parâmetro | Descrição | | --- | --- | | statement\$1name | O nome da instrução que será preparada. O nome deve ser exclusivo no grupo de trabalho. | | statement | Uma consulta SELECT, CTAS ou INSERT INTO. | **nota** O número máximo de instruções preparadas em um grupo de trabalho é mil. ## Exemplos O seguinte exemplo prepara uma consulta selecionada sem parâmetros. ``` PREPARE my_select1 FROM SELECT * FROM nation ``` O seguinte exemplo prepara uma consulta selecionada que inclui parâmetros. Os valores para `productid` e `quantity` serão fornecido pela cláusula `USING` de uma instrução `EXECUTE`: ``` PREPARE my_select2 FROM SELECT order FROM orders WHERE productid = ? and quantity < ? ``` O seguinte exemplo prepara uma consulta de inserção. ``` PREPARE my_insert FROM INSERT INTO cities_usa (city, state) SELECT city, state FROM cities_world WHERE country = ? ``` ## Recursos adicionais [Usar instruções preparadas](querying-with-prepared-statements-querying.md) [EXECUTE](sql-execute.md) [DEALLOCATE PREPARE](sql-deallocate-prepare.md) [INSERT INTO](insert-into.md) # EXECUTE Executa uma instrução preparada com o nome `statement_name`. Os valores dos parâmetros para os pontos de interrogação na declaração preparada estão definidos na cláusula `USING` em uma lista separada por vírgulas. Para criar uma instrução preparada, utilize [PREPARE](sql-prepare.md). ## Resumo ``` EXECUTE statement_name [ USING parameter1[, parameter2, ... ] ] ``` ## Exemplos O seguinte exemplo prepara e executa uma consulta sem parâmetros. ``` PREPARE my_select1 FROM SELECT name FROM nation EXECUTE my_select1 ``` O seguinte exemplo prepara e executa uma consulta com um único parâmetro. ``` PREPARE my_select2 FROM SELECT * FROM "my_database"."my_table" WHERE year = ? EXECUTE my_select2 USING 2012 ``` Isso é equivalente a: ``` SELECT * FROM "my_database"."my_table" WHERE year = 2012 ``` O seguinte exemplo prepara e executa uma consulta com dois parâmetros. ``` PREPARE my_select3 FROM SELECT order FROM orders WHERE productid = ? and quantity < ? EXECUTE my_select3 USING 346078, 12 ``` ## Recursos adicionais [Usar instruções preparadas](querying-with-prepared-statements-querying.md) [PREPARE](sql-prepare.md) [INSERT INTO](insert-into.md) # DEALLOCATE PREPARE Remove a instrução preparada com o nome especificado do conjunto de instruções preparadas no grupo de trabalho atual. ## Resumo ``` DEALLOCATE PREPARE statement_name ``` ## Exemplos O exemplo a seguir remove a instrução preparada `my_select1` do grupo de trabalho atual. ``` DEALLOCATE PREPARE my_select1 ``` ## Recursos adicionais [Usar instruções preparadas](querying-with-prepared-statements-querying.md) [PREPARE](sql-prepare.md) # UNLOAD Grava os resultados da consulta de uma instrução `SELECT` no formato de dados especificado. Os formatos permitidos para `UNLOAD` são Apache Parquet, ORC, Apache Avro e JSON. CSV é o único formato de saída compatível com o comando `SELECT` do Athena, mas você pode usar o comando `UNLOAD`, que é compatível com vários formatos de saída, para delimitar sua consulta `SELECT` e reescrever sua saída em um dos formatos compatíveis com `UNLOAD`. Você pode usar a instrução `CREATE TABLE AS` (CTAS) para gerar dados em formatos não CSV, e as instruções CTAS exigem a criação de uma tabela no Athena. A instrução `UNLOAD` é útil quando você quer gerar os resultados de uma consulta `SELECT` em um formato não CSV, mas não quer a tabela associada. Por exemplo, uma aplicação downstream pode exigir que os resultados de uma consulta `SELECT` estejam no formato JSON, e o Parquet ou o ORC pode ter uma performance melhor do que o CSV se você pretende usar os resultados da consulta `SELECT` para realizar outras análises. ## Considerações e limitações Quando você usar a instrução `UNLOAD` no Athena, lembre-se dos seguintes pontos: + **Sem ordenação global de arquivos**: os resultados de `UNLOAD` são gravados em vários arquivos em paralelo. Se a consulta `SELECT` na instrução `UNLOAD` especificar uma ordem de classificação, o conteúdo de cada arquivo estará na ordem classificada, mas os arquivos não serão classificados entre eles. + **Dados órfãos não excluídos**: em caso de falha, o Athena não tenta excluir os dados órfãos. Esse comportamento é o mesmo nas instruções CTAS e `INSERT INTO`. + **Partições máximas**: o número máximo de partições que podem ser usadas com `UNLOAD` é 100. + **Arquivos manifesto e de metadados**: o Athena gera um arquivo de metadados e um arquivo manifesto de dados para cada consulta `UNLOAD`. O manifesto rastreia os arquivos que a consulta gravou. Os dois arquivos são salvos no local dos resultados das consultas do Athena no Amazon S3. Para obter mais informações, consulte [Identificar arquivos de saída de consultas](querying-finding-output-files.md#querying-identifying-output-files). + **Criptografia**: os arquivos de saída de `UNLOAD` são criptografados de acordo com a configuração de criptografia usada no Amazon S3. Para definir a configuração para criptografar o resultado de `UNLOAD`, você pode usar a [API EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html). + **Instruções preparadas**: `UNLOAD` pode ser usado com instruções preparadas. Para obter informações sobre instruções preparadas no Athena, consulte [Usar consultas parametrizadas](querying-with-prepared-statements.md). + **Cotas de serviço**: o `UNLOAD` usa cotas de consultas em DML. Para obter informações sobre cotas, consulte [Service Quotas](service-limits.md). + **Proprietário do bucket esperado**: a configuração esperada do proprietário do bucket não se aplica ao local de destino do Amazon S3 especificado na consulta `UNLOAD`. A configuração esperada do proprietário do bucket se aplica somente ao local de saída do Amazon S3 que você especificar para os resultados da consulta do Athena. Para obter mais informações, consulte [Especificar um local para resultados de consultas com uso do console do Athena](query-results-specify-location-console.md). ## Sintaxe A instrução `UNLOAD` usa a sintaxe a seguir. ``` UNLOAD (SELECT col_name[, ...] FROM old_table) TO 's3://amzn-s3-demo-bucket/my_folder/' WITH ( property_name = 'expression' [, ...] ) ``` Exceto ao gravar nas partições, o destino `TO` deve especificar um local no Amazon S3 que não tenha dados. Antes de gravar no local especificado, a consulta `UNLOAD` verifica se o local do bucket está vazio. Como `UNLOAD` não grava dados no local especificado se ele já tiver dados, `UNLOAD` não substitui os dados existentes. Para reutilizar um local de bucket como destino para `UNLOAD`, exclua os dados do local do bucket e execute a consulta novamente. Observe que, quando `UNLOAD` grava em partições, esse comportamento é diferente. Se você executar a mesma consulta `UNLOAD` várias vezes com a mesma instrução `SELECT`, o mesmo local `TO` e as mesmas partições, cada consulta `UNLOAD` descarrega os dados no Amazon S3 no local e nas partições especificadas. ### Parâmetros Veja abaixo os valores possíveis para *property\$1name*. ** format = '*file\$1format*' ** Obrigatório. Especifica o formato de arquivo da saída. Os valores possíveis para *file\$1format* são `ORC`, `PARQUET`, `AVRO`, `JSON` ou`TEXTFILE`. ** compression = '*compression\$1format*' ** Opcional. Essa opção é específica aos formatos ORC e Parquet. Para ORC, o padrão é `zlib`, e para Parquet, o padrão é `gzip`. Para obter informações sobre formatos de compactação compatíveis, consulte [Suporte a compactação no Athena](https://docs.aws.amazon.com/athena/latest/ug/compression-formats.html). Essa opção não se aplica ao formato `AVRO`. O Athena usa `gzip` para os formatos `JSON` e `TEXTFILE`. **compression\$1level = *compression\$1level* ** Opcional. O nível de compactação a ser usado para compactação ZSTD. Essa propriedade se aplica apenas à compactação ZSTD. Para obter mais informações, consulte [Usar níveis de compactação ZSTD](compression-support-zstd-levels.md). ** field\$1delimiter = '*delimiter*' ** Opcional. Especifica um delimitador de campo de caractere único para arquivos em CSV, TSV e outros formatos de texto. O exemplo a seguir especifica o delimitador como vírgula. ``` WITH (field_delimiter = ',') ``` Atualmente, não há suporte para delimitadores de campo de vários caracteres. Se você não especificar um delimitador de campo, o caractere octal `\001` (^A) será usado. ** partitioned\$1by = ARRAY[ *col\$1name*[,...] ] ** Opcional. Uma lista matriz de colunas pela qual a saída é particionada. Em sua instrução `SELECT`, verifique se os nomes das colunas particionadas estão listados por último na lista de colunas. ## Exemplos O exemplo a seguir grava a saída de uma consulta `SELECT` no local do Amazon S3 `s3://amzn-s3-demo-bucket/unload_test_1/` usando o formato JSON. ``` UNLOAD (SELECT * FROM old_table) TO 's3://amzn-s3-demo-bucket/unload_test_1/' WITH (format = 'JSON') ``` O exemplo a seguir grava a saída de uma consulta `SELECT` no formato Parquet usando a compactação Snappy. ``` UNLOAD (SELECT * FROM old_table) TO 's3://amzn-s3-demo-bucket/' WITH (format = 'PARQUET',compression = 'SNAPPY') ``` O exemplo a seguir grava quatro colunas no formato de texto, com a saída particionada pela última coluna. ``` UNLOAD (SELECT name1, address1, comment1, key1 FROM table1) TO 's3://amzn-s3-demo-bucket/ partitioned/' WITH (format = 'TEXTFILE', partitioned_by = ARRAY['key1']) ``` O exemplo a seguir descarrega os resultados da consulta no local especificado usando o formato de arquivo Parquet, a compressão ZSTD e o nível 4 de compressão ZSTD. ``` UNLOAD (SELECT * FROM old_table) TO 's3://amzn-s3-demo-bucket/' WITH (format = 'PARQUET', compression = 'ZSTD', compression_level = 4) ``` ## Recursos adicionais + [Simplifique seus pipelines de ETL e ML usando o recurso Amazon Athena UNLOAD](https://aws.amazon.com/blogs/big-data/simplify-your-etl-and-ml-pipelines-using-the-amazon-athena-unload-feature/) no *AWSBlog de Big Data*. # Funções no Amazon Athena Para obter informações sobre as mudanças nas funções entre as versões do mecanismo do Athena, consulte [Versionamento do mecanismo do Athena](engine-versions.md). Para ver uma lista dos fusos horários que podem ser usados com o operador `AT TIME ZONE`, consulte [Usar fusos horários compatíveis](athena-supported-time-zones.md). **Topics** + [Mecanismo Athena versão 3](functions-env3.md) # Funções do mecanismo do Athena versão 3 As funções no mecanismo Athena versão 3 são baseadas no Trino. Para obter informações sobre as funções, operadores e expressões do Trino, consulte [Functions and operators](https://trino.io/docs/current/functions.html) (Funções e operadores) e as seguintes subseções na documentação do Trino. + [Aggregate](https://trino.io/docs/current/functions/aggregate.html) + [Array](https://trino.io/docs/current/functions/array.html) + [Binário](https://trino.io/docs/current/functions/binary.html) + [Bitwise](https://trino.io/docs/current/functions/bitwise.html) + [Color (Cor)](https://trino.io/docs/current/functions/color.html) + [Comparação](https://trino.io/docs/current/functions/comparison.html) + [Condicional](https://trino.io/docs/current/functions/conditional.html) + [Conversão](https://trino.io/docs/current/functions/conversion.html) + [Data e hora](https://trino.io/docs/current/functions/datetime.html) + [Decimal](https://trino.io/docs/current/functions/decimal.html) + [Geoespacial](https://trino.io/docs/current/functions/geospatial.html) + [Log de HyperLogLog](https://trino.io/docs/current/functions/hyperloglog.html) + [Endereço IP](https://trino.io/docs/current/functions/ipaddress.html) + [JSON](https://trino.io/docs/current/functions/json.html) + [Lambda](https://trino.io/docs/current/functions/lambda.html) + [Lógico](https://trino.io/docs/current/functions/logical.html) + [Machine learning](https://trino.io/docs/current/functions/ml.html) + [Mapa](https://trino.io/docs/current/functions/map.html) + [Math (Matemática)](https://trino.io/docs/current/functions/math.html) + [Resumo quantil](https://trino.io/docs/current/functions/qdigest.html) + [Expressão regular](https://trino.io/docs/current/functions/regexp.html) + [Sessão](https://trino.io/docs/current/functions/session.html) + [Definir resumo](https://trino.io/docs/current/functions/setdigest.html) + [String](https://trino.io/docs/current/functions/string.html) + [Tabela](https://trino.io/docs/current/functions/table.html) + [Teradata](https://trino.io/docs/current/functions/teradata.html) + [Resumo em T](https://trino.io/docs/current/functions/tdigest.html) + [URL](https://trino.io/docs/current/functions/url.html) + [UUID](https://trino.io/docs/current/functions/uuid.html) + [Window](https://trino.io/docs/current/functions/window.html) ## função invoker\$1principal() A função `invoker_principal` é exclusiva da versão 3 do mecanismo do Athena e não é encontrada no Trino. Retorna um `VARCHAR` que contém o ARN da entidade principal (perfil do IAM ou identidade do Identity Center) que executou a consulta chamando a função. Por exemplo, se o invocador da consulta usa as permissões de um perfil do IAM para executar a consulta, a função retornará o ARN do perfil do IAM. A função que executa a consulta deve permitir a ação `LakeFormation:GetDataLakePrincipal`. ### Uso ``` SELECT invoker_principal() ``` A tabela a seguir mostra um exemplo de resultado. **** | \$1 | \$1col0 | | --- | --- | | 1 | arn:aws:iam::111122223333:role/Admin | # Usar fusos horários compatíveis É possível utilizar o operador `AT TIME ZONE` em uma instrução para especificar o fuso horário do carimbo de data/hora que será retornado, como no seguinte exemplo: ``` SELECT timestamp '2012-10-31 01:00 UTC' AT TIME ZONE 'America/Los_Angeles' AS la_time; ``` **Resultados** ``` la_time 2012-10-30 18:00:00.000 America/Los_Angeles ``` Para obter uma lista de fusos horários compatíveis com o Athena, expanda [Lista de fusos horários compatíveis](#athena-supported-time-zones-list) no final deste tópico. ## Funções e exemplos de fuso horário Veja a seguir algumas funções e exemplos adicionais relacionados a fuso horário. + **at\$1timezone(*timestamp*, *zone*)**: retorna o valor de *timestamp* no horário local correspondente para *zone*. **Exemplo** ``` SELECT at_timezone(timestamp '2021-08-22 00:00 UTC', 'Canada/Newfoundland') ``` **Resultado** ``` 2021-08-21 21:30:00.000 Canada/Newfoundland ``` + **timezone\$1hour(*timestamp*)**: retorna a hora do deslocamento do fuso horário do timestamp como um `bigint`. **Exemplo** ``` SELECT timezone_hour(timestamp '2021-08-22 04:00 UTC' AT TIME ZONE 'Canada/Newfoundland') ``` **Resultado** ``` -2 ``` + **timezone\$1minute(*timestamp*)**: retorna a hora do deslocamento do fuso horário do *timestamp* como um `bigint`. **Exemplo** ``` SELECT timezone_minute(timestamp '2021-08-22 04:00 UTC' AT TIME ZONE 'Canada/Newfoundland') ``` **Resultado** ``` -30 ``` + **with\$1timezone(*timestamp*, *zone*)**: retorna um timestamp com fuso horário dos valores *timestamp* e *zone* especificado. **Exemplo** ``` SELECT with_timezone(timestamp '2021-08-22 04:00', 'Canada/Newfoundland') ``` **Resultado** ``` 2021-08-22 04:00:00.000 Canada/Newfoundland ``` ## Lista de fusos horários compatíveis A lista a seguir contém os fusos horários que podem ser usados com o operador `AT TIME ZONE` no Athena. Para obter funções e exemplos adicionais relacionados a fuso horário, consulte [Funções e exemplos de fuso horário](#athena-supported-time-zones-functions-examples). ``` Africa/Abidjan Africa/Accra Africa/Addis_Ababa Africa/Algiers Africa/Asmara Africa/Asmera Africa/Bamako Africa/Bangui Africa/Banjul Africa/Bissau Africa/Blantyre Africa/Brazzaville Africa/Bujumbura Africa/Cairo Africa/Casablanca Africa/Ceuta Africa/Conakry Africa/Dakar Africa/Dar_es_Salaam Africa/Djibouti Africa/Douala Africa/El_Aaiun Africa/Freetown Africa/Gaborone Africa/Harare Africa/Johannesburg Africa/Juba Africa/Kampala Africa/Khartoum Africa/Kigali Africa/Kinshasa Africa/Lagos Africa/Libreville Africa/Lome Africa/Luanda Africa/Lubumbashi Africa/Lusaka Africa/Malabo Africa/Maputo Africa/Maseru Africa/Mbabane Africa/Mogadishu Africa/Monrovia Africa/Nairobi Africa/Ndjamena Africa/Niamey Africa/Nouakchott Africa/Ouagadougou Africa/Porto-Novo Africa/Sao_Tome Africa/Timbuktu Africa/Tripoli Africa/Tunis Africa/Windhoek America/Adak America/Anchorage America/Anguilla America/Antigua America/Araguaina America/Argentina/Buenos_Aires America/Argentina/Catamarca America/Argentina/ComodRivadavia America/Argentina/Cordoba America/Argentina/Jujuy America/Argentina/La_Rioja America/Argentina/Mendoza America/Argentina/Rio_Gallegos America/Argentina/Salta America/Argentina/San_Juan America/Argentina/San_Luis America/Argentina/Tucuman America/Argentina/Ushuaia America/Aruba America/Asuncion America/Atikokan America/Atka America/Bahia America/Bahia_Banderas America/Barbados America/Belem America/Belize America/Blanc-Sablon America/Boa_Vista America/Bogota America/Boise America/Buenos_Aires America/Cambridge_Bay America/Campo_Grande America/Cancun America/Caracas America/Catamarca America/Cayenne America/Cayman America/Chicago America/Chihuahua America/Coral_Harbour America/Cordoba America/Costa_Rica America/Creston America/Cuiaba America/Curacao America/Danmarkshavn America/Dawson America/Dawson_Creek America/Denver America/Detroit America/Dominica America/Edmonton America/Eirunepe America/El_Salvador America/Ensenada America/Fort_Nelson America/Fort_Wayne America/Fortaleza America/Glace_Bay America/Godthab America/Goose_Bay America/Grand_Turk America/Grenada America/Guadeloupe America/Guatemala America/Guayaquil America/Guyana America/Halifax America/Havana America/Hermosillo America/Indiana/Indianapolis America/Indiana/Knox America/Indiana/Marengo America/Indiana/Petersburg America/Indiana/Tell_City America/Indiana/Vevay America/Indiana/Vincennes America/Indiana/Winamac America/Indianapolis America/Inuvik America/Iqaluit America/Jamaica America/Jujuy America/Juneau America/Kentucky/Louisville America/Kentucky/Monticello America/Knox_IN America/Kralendijk America/La_Paz America/Lima America/Los_Angeles America/Louisville America/Lower_Princes America/Maceio America/Managua America/Manaus America/Marigot America/Martinique America/Matamoros America/Mazatlan America/Mendoza America/Menominee America/Merida America/Metlakatla America/Mexico_City America/Miquelon America/Moncton America/Monterrey America/Montevideo America/Montreal America/Montserrat America/Nassau America/New_York America/Nipigon America/Nome America/Noronha America/North_Dakota/Beulah America/North_Dakota/Center America/North_Dakota/New_Salem America/Ojinaga America/Panama America/Pangnirtung America/Paramaribo America/Phoenix America/Port-au-Prince America/Port_of_Spain America/Porto_Acre America/Porto_Velho America/Puerto_Rico America/Punta_Arenas America/Rainy_River America/Rankin_Inlet America/Recife America/Regina America/Resolute America/Rio_Branco America/Rosario America/Santa_Isabel America/Santarem America/Santiago America/Santo_Domingo America/Sao_Paulo America/Scoresbysund America/Shiprock America/Sitka America/St_Barthelemy America/St_Johns America/St_Kitts America/St_Lucia America/St_Thomas America/St_Vincent America/Swift_Current America/Tegucigalpa America/Thule America/Thunder_Bay America/Tijuana America/Toronto America/Tortola America/Vancouver America/Virgin America/Whitehorse America/Winnipeg America/Yakutat America/Yellowknife Antarctica/Casey Antarctica/Davis Antarctica/DumontDUrville Antarctica/Macquarie Antarctica/Mawson Antarctica/McMurdo Antarctica/Palmer Antarctica/Rothera Antarctica/South_Pole Antarctica/Syowa Antarctica/Troll Antarctica/Vostok Arctic/Longyearbyen Asia/Aden Asia/Almaty Asia/Amman Asia/Anadyr Asia/Aqtau Asia/Aqtobe Asia/Ashgabat Asia/Ashkhabad Asia/Atyrau Asia/Baghdad Asia/Bahrain Asia/Baku Asia/Bangkok Asia/Barnaul Asia/Beirut Asia/Bishkek Asia/Brunei Asia/Calcutta Asia/Chita Asia/Choibalsan Asia/Chongqing Asia/Chungking Asia/Colombo Asia/Dacca Asia/Damascus Asia/Dhaka Asia/Dili Asia/Dubai Asia/Dushanbe Asia/Gaza Asia/Harbin Asia/Hebron Asia/Ho_Chi_Minh Asia/Hong_Kong Asia/Hovd Asia/Irkutsk Asia/Istanbul Asia/Jakarta Asia/Jayapura Asia/Jerusalem Asia/Kabul Asia/Kamchatka Asia/Karachi Asia/Kashgar Asia/Kathmandu Asia/Katmandu Asia/Khandyga Asia/Kolkata Asia/Krasnoyarsk Asia/Kuala_Lumpur Asia/Kuching Asia/Kuwait Asia/Macao Asia/Macau Asia/Magadan Asia/Makassar Asia/Manila Asia/Muscat Asia/Nicosia Asia/Novokuznetsk Asia/Novosibirsk Asia/Omsk Asia/Oral Asia/Phnom_Penh Asia/Pontianak Asia/Pyongyang Asia/Qatar Asia/Qyzylorda Asia/Rangoon Asia/Riyadh Asia/Saigon Asia/Sakhalin Asia/Samarkand Asia/Seoul Asia/Shanghai Asia/Singapore Asia/Srednekolymsk Asia/Taipei Asia/Tashkent Asia/Tbilisi Asia/Tehran Asia/Tel_Aviv Asia/Thimbu Asia/Thimphu Asia/Tokyo Asia/Tomsk Asia/Ujung_Pandang Asia/Ulaanbaatar Asia/Ulan_Bator Asia/Urumqi Asia/Ust-Nera Asia/Vientiane Asia/Vladivostok Asia/Yakutsk Asia/Yangon Asia/Yekaterinburg Asia/Yerevan Atlantic/Azores Atlantic/Bermuda Atlantic/Canary Atlantic/Cape_Verde Atlantic/Faeroe Atlantic/Faroe Atlantic/Jan_Mayen Atlantic/Madeira Atlantic/Reykjavik Atlantic/South_Georgia Atlantic/St_Helena Atlantic/Stanley Australia/ACT Australia/Adelaide Australia/Brisbane Australia/Broken_Hill Australia/Canberra Australia/Currie Australia/Darwin Australia/Eucla Australia/Hobart Australia/LHI Australia/Lindeman Australia/Lord_Howe Australia/Melbourne Australia/NSW Australia/North Australia/Perth Australia/Queensland Australia/South Australia/Sydney Australia/Tasmania Australia/Victoria Australia/West Australia/Yancowinna Brazil/Acre Brazil/DeNoronha Brazil/East Brazil/West CET CST6CDT Canada/Atlantic Canada/Central Canada/Eastern Canada/Mountain Canada/Newfoundland Canada/Pacific Canada/Saskatchewan Canada/Yukon Chile/Continental Chile/EasterIsland Cuba EET EST5EDT Egypt Eire Europe/Amsterdam Europe/Andorra Europe/Astrakhan Europe/Athens Europe/Belfast Europe/Belgrade Europe/Berlin Europe/Bratislava Europe/Brussels Europe/Bucharest Europe/Budapest Europe/Busingen Europe/Chisinau Europe/Copenhagen Europe/Dublin Europe/Gibraltar Europe/Guernsey Europe/Helsinki Europe/Isle_of_Man Europe/Istanbul Europe/Jersey Europe/Kaliningrad Europe/Kiev Europe/Kirov Europe/Lisbon Europe/Ljubljana Europe/London Europe/Luxembourg Europe/Madrid Europe/Malta Europe/Mariehamn Europe/Minsk Europe/Monaco Europe/Moscow Europe/Nicosia Europe/Oslo Europe/Paris Europe/Podgorica Europe/Prague Europe/Riga Europe/Rome Europe/Samara Europe/San_Marino Europe/Sarajevo Europe/Simferopol Europe/Skopje Europe/Sofia Europe/Stockholm Europe/Tallinn Europe/Tirane Europe/Tiraspol Europe/Ulyanovsk Europe/Uzhgorod Europe/Vaduz Europe/Vatican Europe/Vienna Europe/Vilnius Europe/Volgograd Europe/Warsaw Europe/Zagreb Europe/Zaporozhye Europe/Zurich GB GB-Eire Hongkong Iceland Indian/Antananarivo Indian/Chagos Indian/Christmas Indian/Cocos Indian/Comoro Indian/Kerguelen Indian/Mahe Indian/Maldives Indian/Mauritius Indian/Mayotte Indian/Reunion Iran Israel Jamaica Japan Kwajalein Libya MET MST7MDT Mexico/BajaNorte Mexico/BajaSur Mexico/General NZ NZ-CHAT Navajo PRC PST8PDT Pacific/Apia Pacific/Auckland Pacific/Bougainville Pacific/Chatham Pacific/Chuuk Pacific/Easter Pacific/Efate Pacific/Enderbury Pacific/Fakaofo Pacific/Fiji Pacific/Funafuti Pacific/Galapagos Pacific/Gambier Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu Pacific/Johnston Pacific/Kiritimati Pacific/Kosrae Pacific/Kwajalein Pacific/Majuro Pacific/Marquesas Pacific/Midway Pacific/Nauru Pacific/Niue Pacific/Norfolk Pacific/Noumea Pacific/Pago_Pago Pacific/Palau Pacific/Pitcairn Pacific/Pohnpei Pacific/Ponape Pacific/Port_Moresby Pacific/Rarotonga Pacific/Saipan Pacific/Samoa Pacific/Tahiti Pacific/Tarawa Pacific/Tongatapu Pacific/Truk Pacific/Wake Pacific/Wallis Pacific/Yap Poland Portugal ROK Singapore Turkey US/Alaska US/Aleutian US/Arizona US/Central US/East-Indiana US/Eastern US/Hawaii US/Indiana-Starke US/Michigan US/Mountain US/Pacific US/Pacific-New US/Samoa W-SU WET ``` # Instruções DDL Use as instruções da linguagem de definição de dados (DDL) compatível apresentadas aqui diretamente no Athena. O mecanismo de consulta do Athena é baseado em parte na [DDL do HiveQL](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL). O Athena não aceita todas as instruções DDL, e há algumas diferenças entre a DDL do HiveQL e do Athena. Para obter mais informações, consulte os tópicos de referência nesta seção e em [DDL incompatível](unsupported-ddl.md). **Topics** + [DDL incompatível](unsupported-ddl.md) + [ALTER DATABASE SET DBPROPERTIES](alter-database-set-dbproperties.md) + [ALTER TABLE ADD COLUMNS](alter-table-add-columns.md) + [ALTER TABLE ADD PARTITION](alter-table-add-partition.md) + [ALTER TABLE CHANGE COLUMN](alter-table-change-column.md) + [ALTER TABLE DROP PARTITION](alter-table-drop-partition.md) + [ALTER TABLE RENAME PARTITION](alter-table-rename-partition.md) + [ALTER TABLE REPLACE COLUMNS](alter-table-replace-columns.md) + [ALTER TABLE SET LOCATION](alter-table-set-location.md) + [ALTER TABLE SET TBLPROPERTIES](alter-table-set-tblproperties.md) + [ALTER VIEW DIALECT](alter-view-dialect.md) + [CREATE DATABASE](create-database.md) + [CREATE TABLE](create-table.md) + [CREATE TABLE AS](create-table-as.md) + [CREATE VIEW](create-view.md) + [DESCRIBE](describe-table.md) + [DESCRIBE VIEW](describe-view.md) + [DROP DATABASE](drop-database.md) + [DROP TABLE](drop-table.md) + [DROP VIEW](drop-view.md) + [MSCK REPAIR TABLE](msck-repair-table.md) + [SHOW COLUMNS](show-columns.md) + [SHOW CREATE TABLE](show-create-table.md) + [SHOW CREATE VIEW](show-create-view.md) + [SHOW DATABASES](show-databases.md) + [SHOW PARTITIONS](show-partitions.md) + [SHOW TABLES](show-tables.md) + [SHOW TBLPROPERTIES](show-tblproperties.md) + [SHOW VIEWS](show-views.md) # DDL incompatível As instruções DDL a seguir não são aceitas no Athena. Para obter as instruções DDL compatíveis com as tabelas do Iceberg no Athena, consulte [Evoluir o esquema de tabelas do Iceberg](querying-iceberg-evolving-table-schema.md) e [Executar outras operações de DDL em tabelas do Iceberg](querying-iceberg-additional-operations.md). + ALTER INDEX + ALTER TABLE *table\$1name* ARCHIVE PARTITION + ALTER TABLE *table\$1name* CLUSTERED BY + ALTER TABLE *table\$1name* DROP COLUMN (compatível com as tabelas do Iceberg) + ALTER TABLE *table\$1name* EXCHANGE PARTITION + ALTER TABLE *table\$1name* NOT CLUSTERED + ALTER TABLE *table\$1name* NOT SKEWED + ALTER TABLE *table\$1name* NOT SORTED + ALTER TABLE *table\$1name* NOT STORED AS DIRECTORIES + ALTER TABLE *table\$1name* partitionSpec CHANGE COLUMNS + ALTER TABLE *table\$1name* partitionSpec COMPACT + ALTER TABLE *table\$1name* partitionSpec CONCATENATE + ALTER TABLE *table\$1name* partitionSpec SET FILEFORMAT + ALTER TABLE *table\$1name* RENAME TO (compatível com as tabelas do Iceberg) + ALTER TABLE *table\$1name* SET SERDEPROPERTIES + ALTER TABLE *table\$1name* SET SKEWED LOCATION + ALTER TABLE *table\$1name* SKEWED BY + ALTER TABLE *table\$1name* TOUCH + ALTER TABLE *table\$1name* UNARCHIVE PARTITION + COMMIT + CREATE INDEX + CRIAR PERFIL + CREATE TABLE *table\$1name* LIKE *existing\$1table\$1name* + CREATE TEMPORARY MACRO + DELETE FROM + DESCRIBE DATABASE + DFS + DROP INDEX + DROP ROLE + DROP TEMPORARY MACRO + EXPORT TABLE + GRANT ROLE + IMPORT TABLE + LOCK DATABASE + LOCK TABLE + REVOKE ROLE + ROLLBACK + SHOW COMPACTIONS + SHOW CURRENT ROLES + SHOW GRANT + SHOW INDEXES + SHOW LOCKS + SHOW PRINCIPALS + SHOW ROLE GRANT + SHOW ROLES + MOSTRAR ESTATÍSTICAS + SHOW TRANSACTIONS + START TRANSACTION + UNLOCK DATABASE + UNLOCK TABLE # ALTER DATABASE SET DBPROPERTIES Cria uma ou mais propriedades para um banco de dados. O uso de `DATABASE` e `SCHEMA` é intercambiável. Eles são iguais. ## Resumo ``` ALTER {DATABASE|SCHEMA} database_name SET DBPROPERTIES ('property_name'='property_value' [, ...] ) ``` ## Parâmetros **SET DBPROPERTIES ('property\$1name'='property\$1value' [, ...]** Especifica uma propriedade ou propriedades para o banco de dados chamado `property_name` e estabelece o valor para cada uma das propriedades, respectivamente como `property_value`. Se `property_name` já existir, o valor anterior será substituído por `property_value`. ## Exemplos ``` ALTER DATABASE jd_datasets SET DBPROPERTIES ('creator'='John Doe', 'department'='applied mathematics'); ``` ``` ALTER SCHEMA jd_datasets SET DBPROPERTIES ('creator'='Jane Doe'); ``` # ALTER TABLE ADD COLUMNS Adicione uma ou mais colunas a uma tabela existente. Quando a sintaxe opcional de `PARTITION` é usada, os metadados da partição são atualizados. ## Resumo ``` ALTER TABLE table_name [PARTITION (partition_col1_name = partition_col1_value [,partition_col2_name = partition_col2_value][,...])] ADD COLUMNS (col_name data_type) ``` ## Parâmetros **PARTITION (partition\$1col\$1name = partition\$1col\$1value [,...])** Cria uma partição com as combinações de nome/valor de coluna que você especificar. Coloque `partition_col_value` entre aspas somente se o tipo de dados da coluna for uma string. **ADD COLUMNS (col\$1name data\$1type [,col\$1name data\$1type,...])** Adiciona colunas após colunas existentes, mas antes das colunas de partição. ## Exemplos ``` ALTER TABLE events ADD COLUMNS (eventowner string) ``` ``` ALTER TABLE events PARTITION (awsregion='us-west-2') ADD COLUMNS (event string) ``` ``` ALTER TABLE events PARTITION (awsregion='us-west-2') ADD COLUMNS (eventdescription string) ``` ## Observações + Para ver uma nova coluna de tabela no painel de navegação do editor de consultas do Athena depois de executar `ALTER TABLE ADD COLUMNS`, atualize manualmente a lista de tabelas no editor e expanda a tabela outra vez. + `ALTER TABLE ADD COLUMNS` não funciona em colunas com o tipo de dados `date`. Para contornar esse problema, use o tipo de dados `timestamp`. # ALTER TABLE ADD PARTITION Cria uma ou mais colunas de partição para a tabela. Cada partição consiste em uma ou mais combinações de nome/valor de coluna distintas. Um diretório de dados à parte é criado para cada combinação especificada, o que pode melhorar a performance da consulta em algumas circunstâncias. As colunas particionadas não existem dentro da própria tabela de dados. Dessa forma, se usar o nome de uma coluna com o mesmo nome de uma coluna na própria tabela, você receberá um erro. Para obter mais informações, consulte [Particionar dados](partitions.md). No Athena, uma tabela e suas partições devem usar os mesmos formatos de dados, mas os esquemas podem ser diferentes. Para obter mais informações, consulte [Atualizar tabelas com partições](updates-and-partitions.md). Para obter informações sobre as permissões no nível do recurso necessárias nas políticas do IAM (incluindo `glue:CreatePartition`), consulte [Permissões da API do AWS Glue: referência de ações e recursos](https://docs.aws.amazon.com/glue/latest/dg/api-permissions-reference.html) e [Configurar o acesso a bancos de dados e tabelas no AWS Glue Data Catalog](fine-grained-access-to-glue-resources.md). Para obter informações sobre solução de problemas de permissões ao usar o Athena, consulte a seção [Permissões](troubleshooting-athena.md#troubleshooting-athena-permissions) do tópico [Solucionar problemas no Athena](troubleshooting-athena.md). ## Resumo ``` ALTER TABLE table_name ADD [IF NOT EXISTS] PARTITION (partition_col1_name = partition_col1_value [,partition_col2_name = partition_col2_value] [,...]) [LOCATION 'location1'] [PARTITION (partition_colA_name = partition_colA_value [,partition_colB_name = partition_colB_value [,...])] [LOCATION 'location2'] [,...] ``` ## Parâmetros Ao adicionar uma partição, você especifica um ou mais pares de nome/valor de coluna para a partição e o caminho do Amazon S3 onde residem os arquivos de dados dessa partição. **[IF NOT EXISTS]** Suprimirá o erro se uma partição com a mesma definição já existir. **PARTITION (partition\$1col\$1name = partition\$1col\$1value [,...])** Cria uma partição com as combinações de nome/valor de coluna que você especificar. Coloque `partition_col_value` entre caracteres de string somente se o tipo de dados da coluna for uma string. **[LOCATION 'location']** Especifica o diretório no qual armazenar a partição definida pela instrução anterior. A cláusula `LOCATION` é opcional quando os dados usam particionamento no estilo Hive (`pk1=v1/pk2=v2/pk3=v3`). Com o particionamento no estilo Hive, o URI completo do Amazon S3 é estruturado automaticamente com base na localização da tabela, nos nomes das chaves de partição e nos valores de chave de partição. Para obter mais informações, consulte [Particionar dados](partitions.md). ## Considerações O Amazon Athena não impõe um limite específico ao número de partições que você pode adicionar em uma única instrução DDL `ALTER TABLE ADD PARTITION`. No entanto, se você precisar adicionar um número significativo de partições, considere dividir a operação em lotes menores para evitar possíveis problemas de desempenho. O exemplo a seguir usa comandos sucessivos para adicionar partições individualmente e usa `IF NOT EXISTS` para evitar a adição de duplicatas. ``` ALTER TABLE table_name ADD IF NOT EXISTS PARTITION (ds='2023-01-01') ALTER TABLE table_name ADD IF NOT EXISTS PARTITION (ds='2023-01-02') ALTER TABLE table_name ADD IF NOT EXISTS PARTITION (ds='2023-01-03') ``` Ao trabalhar com partições no Athena, lembre-se dos seguintes pontos: + Embora o Athena ofereça suporte a consulta a tabelas do AWS Glue com 10 milhões de partições, o Athena não pode ler mais de 1 milhão de partições em uma única varredura. + Para otimizar suas consultas e reduzir o número de partições verificadas, considere estratégias como remoção de partições ou uso de índices de partição. Para considerações adicionais sobre como trabalhar com partições no Athena, consulte [Particionar dados](partitions.md). ## Exemplos O exemplo a seguir adiciona uma única partição a uma tabela para dados particionados no estilo Hive. ``` ALTER TABLE orders ADD PARTITION (dt = '2016-05-14', country = 'IN'); ``` O exemplo a seguir adiciona múltiplas partições a uma tabela para dados particionados no estilo Hive. ``` ALTER TABLE orders ADD PARTITION (dt = '2016-05-31', country = 'IN') PARTITION (dt = '2016-06-01', country = 'IN'); ``` Quando a tabela não serve para dados particionados no estilo Hive, a cláusula `LOCATION` é obrigatória e deve ser o URI completo do Amazon S3 para o prefixo que contém os dados da partição. ``` ALTER TABLE orders ADD PARTITION (dt = '2016-05-31', country = 'IN') LOCATION 's3://amzn-s3-demo-bucket/path/to/INDIA_31_May_2016/' PARTITION (dt = '2016-06-01', country = 'IN') LOCATION 's3://amzn-s3-demo-bucket/path/to/INDIA_01_June_2016/'; ``` Para ignorar erros quando a partição já existe, use a cláusula `IF NOT EXISTS`, como no exemplo a seguir. ``` ALTER TABLE orders ADD IF NOT EXISTS PARTITION (dt = '2016-05-14', country = 'IN'); ``` ## Arquivos de zero byte no formato `_$folder$` Se você executar uma instrução `ALTER TABLE ADD PARTITION` e especificar erroneamente uma partição que já existe e uma localização incorreta do Amazon S3, serão criados arquivos de espaço reservado de zero byte do formato `partition_value_$folder$` no Amazon S3. Você precisa remover esses arquivos manualmente. Para evitar que isso aconteça, use a sintaxe `ADD IF NOT EXISTS` na instrução `ALTER TABLE ADD PARTITION`, como no exemplo a seguir. ``` ALTER TABLE table_name ADD IF NOT EXISTS PARTITION […] ``` # ALTER TABLE CHANGE COLUMN Altera o nome, o tipo, a ordem ou o comentário de uma coluna em uma tabela. ## Resumo ``` ALTER TABLE [db_name.]table_name CHANGE [COLUMN] col_old_name col_new_name column_type [COMMENT col_comment] [FIRST|AFTER column_name] ``` ## Exemplos O exemplo a seguir altera o nome da coluna de `area` para `zip`, torna o tipo de dados inteiro e coloca a coluna renomeada depois da coluna `id`. ``` ALTER TABLE example_table CHANGE COLUMN area zip int AFTER id ``` O exemplo a seguir adiciona um comentário à coluna `zip` nos metadados para `example_table`. Para ver o comentário, use o comando da AWS CLI [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/athena/get-table-metadata.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/athena/get-table-metadata.html) ou acesse o esquema da tabela no console do AWS Glue. ``` ALTER TABLE example_table CHANGE COLUMN zip zip int COMMENT 'USA zipcode' ``` # ALTER TABLE DROP PARTITION Descarta uma ou mais partições especificadas para a tabela nomeada. ## Resumo ``` ALTER TABLE table_name DROP [IF EXISTS] PARTITION (partition_spec) [, PARTITION (partition_spec)] ``` ## Parâmetros **[SE EXISTIR]** Suprime a mensagem de erro se a partição especificada não existir. **PARTIÇÃO (partition\$1spec)** Cada `partition_spec` especifica uma combinação de nome de coluna e valor no formato `partition_col_name = partition_col_value [,...]`. ## Exemplos ``` ALTER TABLE orders DROP PARTITION (dt = '2014-05-14', country = 'IN'); ``` ``` ALTER TABLE orders DROP PARTITION (dt = '2014-05-14', country = 'IN'), PARTITION (dt = '2014-05-15', country = 'IN'); ``` ## Observações A instrução `ALTER TABLE DROP PARTITION` não fornece uma sintaxe única para descartar todas as partições de uma só vez nem suporta critérios de filtragem para especificar um intervalo de partições a serem eliminadas. Como solução de contorno, use as ações [GetPartitions](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-catalog-partitions.html#aws-glue-api-catalog-partitions-GetPartitions) e [BatchDeletePartition](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-catalog-partitions.html#aws-glue-api-catalog-partitions-BatchDeletePartition) da API do AWS Glue no desenvolvimento de scripts. A ação `GetPartitions` suporta expressões de filtro complexas como as de uma expressão `WHERE` em SQL. Depois de usar `GetPartitions` para criar uma lista filtrada das partições a serem excluídas, você pode usar a ação `BatchDeletePartition` para excluir as partições em lotes de 25. # ALTER TABLE RENAME PARTITION Renomeia um valor de partição. **nota** ALTER TABLE RENAME PARTITION não renomeia as colunas de partição. Para alterar o nome de uma coluna de partição, você pode usar o console do AWS Glue. Para obter mais informações, consulte [Renomear uma coluna de partição no AWS Glue](#alter-table-rename-partition-column-name) adiante neste documento. ## Resumo Para a tabela chamada `table_name`, renomeia o valor da partição especificado por `partition_spec` para o valor especificado por `new_partition_spec`. ``` ALTER TABLE table_name PARTITION (partition_spec) RENAME TO PARTITION (new_partition_spec) ``` ## Parâmetros **PARTIÇÃO (partition\$1spec)** Cada `partition_spec` especifica uma combinação de nome de coluna e valor no formato `partition_col_name = partition_col_value [,...]`. ## Exemplos ``` ALTER TABLE orders PARTITION (dt = '2014-05-14', country = 'IN') RENAME TO PARTITION (dt = '2014-05-15', country = 'IN'); ``` ## Renomear uma coluna de partição no AWS Glue Use o procedimento a seguir para renomear colunas de partição no console do AWS Glue. **Para renomear uma coluna de partição de tabela no console do AWS Glue** 1. Faça login no Console de gerenciamento da AWS e abra o console do AWS Glue em [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/). 1. No painel de navegação, selecione **Tabelas**. 1. Na página **Tabelas**, use a caixa de pesquisa **Filtrar tabelas** para localizar a tabela que você deseja alterar. 1. Na coluna **Nome**, escolha o link da tabela que você deseja alterar. 1. Na página de detalhes da tabela, na seção **Esquema**, siga um destes procedimentos: + Para fazer a alteração do nome no formato JSON, escolha **Editar esquema como JSON**. + Para alterar o nome diretamente, escolha **Editar esquema**. Esse procedimento escolhe **Editar esquema**. 1. Marque a caixa de seleção referente à coluna particionada que você deseja renomear e escolha **Editar**. 1. Na caixa de diálogo **Editar entrada do esquema**, em **Nome**, insira o novo nome para a coluna de partição. 1. Selecione **Salvar como nova versão da tabela**. Essa ação atualiza o nome da coluna da partição e preserva o histórico de evolução do esquema sem criar outra cópia física dos dados. 1. Para comparar as versões da tabela, na página de detalhes da tabela, escolha **Ações** e, em seguida, **Comparar versões**. ## Recursos adicionais Para obter mais informações sobre particionamento, consulte [Particionar dados](partitions.md). # ALTER TABLE REPLACE COLUMNS Remove todas as colunas existentes de uma tabela criada com [LazySimpleSerDe](lazy-simple-serde.md) e as substitui pelo conjunto de colunas especificado. Quando a sintaxe opcional de `PARTITION` é usada, os metadados da partição são atualizados. Você também pode usar `ALTER TABLE REPLACE COLUMNS` para descartar as colunas especificando apenas as colunas que deseja manter. ## Resumo ``` ALTER TABLE table_name [PARTITION (partition_col1_name = partition_col1_value [,partition_col2_name = partition_col2_value][,...])] REPLACE COLUMNS (col_name data_type [, col_name data_type, ...]) ``` ## Parâmetros **PARTITION (partition\$1col\$1name = partition\$1col\$1value [,...])** Especifica uma partição com as combinações de nome/valor de coluna que você especificar. Coloque `partition_col_value` entre aspas somente se o tipo de dados da coluna for uma string. **REPLACE COLUMNS (col\$1name data\$1type [,col\$1name data\$1type,...])** Substitui as colunas existentes pelos nomes e tipos de dados de coluna especificados. ## Observações + Para ver a alteração nas colunas de tabela no painel de navegação do editor de consultas do Athena após executar `ALTER TABLE REPLACE COLUMNS`, pode ser necessário atualizar manualmente a tabela no editor e depois expandir a tabela outra vez. + `ALTER TABLE REPLACE COLUMNS` não funciona em colunas com o tipo de dados `date`. Para contornar esse problema, use o tipo de dados `timestamp` na tabela. + Observe que, mesmo que se você for substituir apenas uma coluna, a sintaxe deverá ser `ALTER TABLE table-name REPLACE COLUMNS`, com *columns* no plural. Você deve especificar não apenas a coluna que deseja substituir, mas as colunas que deseja manter, do contrário, as colunas que não especificadas serão descartadas. Essa sintaxe e esse comportamento derivam da DDL do Apache Hive. Para referência, consulte [Add/Replace Columns](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL#LanguageManualDDL-Add/ReplaceColumns) (Adicionar/substituir colunas) na documentação do Apache. ## Exemplo No exemplo a seguir, a tabela `names_cities`, que foi criada usando o [LazySimpleSerDe](lazy-simple-serde.md), tem três colunas chamadas `col1`, `col2` e `col3`. Todas as colunas são do tipo `string`. Para mostrar as colunas na tabela, o comando a seguir usa a instrução [SHOW COLUMNS](show-columns.md). ``` SHOW COLUMNS IN names_cities ``` Resultado da consulta: ``` col1 col2 col3 ``` O comando `ALTER TABLE REPLACE COLUMNS` a seguir substitui os nomes das colunas por `first_name`,`last_name` e `city`. Os dados de origem subjacentes não são afetados. ``` ALTER TABLE names_cities REPLACE COLUMNS (first_name string, last_name string, city string) ``` Para testar o resultado, `SHOW COLUMNS` é executado novamente. ``` SHOW COLUMNS IN names_cities ``` Resultado da consulta: ``` first_name last_name city ``` Outra maneira de mostrar os novos nomes de coluna é exibir a [previsualização da tabela](creating-tables-showing-table-information.md) no editor de consultas do Athena ou executar o sua própria consulta `SELECT`. # ALTER TABLE SET LOCATION Altera o local da tabela chamada `table_name` e, como opção, uma partição com `partition_spec`. ## Resumo ``` ALTER TABLE table_name [ PARTITION (partition_spec) ] SET LOCATION 'new location' ``` ## Parâmetros **PARTIÇÃO (partition\$1spec)** Especifica a partição com parâmetros `partition_spec` cujo local você deseja alterar. O `partition_spec` especifica uma combinação nome/valor na forma `partition_col_name = partition_col_value`. **SET LOCATION 'new location'** Especifica o novo local, que deve ser um local do Amazon S3. Para obter informações sobre sintaxe, consulte [Local da tabela no Amazon S3](tables-location-format.md). ## Exemplos ``` ALTER TABLE customers PARTITION (zip='98040', state='WA') SET LOCATION 's3://amzn-s3-demo-bucket/custdata/'; ``` # ALTER TABLE SET TBLPROPERTIES Adiciona propriedades de metadados personalizadas ou predefinidas a uma tabela e define seus valores atribuídos. Para ver as propriedades em uma tabela, use o comando [SHOW TBLPROPERTIES](show-tblproperties.md). As [tabelas gerenciadas](https://cwiki.apache.org/confluence/display/Hive/Managed+vs.+External+Tables) do Apache Hive não são permitidas, portanto, a definição de `'EXTERNAL'='FALSE'` não tem efeito. ## Resumo ``` ALTER TABLE table_name SET TBLPROPERTIES ('property_name' = 'property_value' [ , ... ]) ``` ## Parâmetros **SET TBLPROPERTIES ('property\$1name' = 'property\$1value' [ , ... ])** Especifica as propriedades de metadados a serem adicionadas como `property_name` e o valor para cada uma como `property value`. Se `property_name` já existir, o valor será definido como o `property_value` recém-especificado. As propriedades de tabela predefinidas a seguir têm usos especiais. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/alter-table-set-tblproperties.html) ## Exemplos O exemplo a seguir adiciona uma nota de comentário às propriedades da tabela. ``` ALTER TABLE orders SET TBLPROPERTIES ('notes'="Please don't drop this table."); ``` O exemplo a seguir modifica a tabela `existing_table` para usar o formato de arquivo Parquet com compactação ZSTD nível 4. ``` ALTER TABLE existing_table SET TBLPROPERTIES ('parquet.compression' = 'ZSTD', 'compression_level' = 4) ``` # ALTER VIEW DIALECT Adiciona ou remove um dialeto do mecanismo de uma visualização do AWS Glue Data Catalog. Aplica-se somente às visualizações do AWS Glue Data Catalog. Requer permissões do administrador ou definidor do `Lake Formation`. Para obter mais informações sobre visualizações do AWS Glue Data Catalog, consulte [Usar visualizações do Catálogo de Dados no Athena](views-glue.md). ## Sintaxe ``` ALTER VIEW name [ FORCE ] [ ADD|UPDATE ] DIALECT AS query ``` ``` ALTER VIEW name [ DROP ] DIALECT ``` **FORCE** A palavra-chave `FORCE` faz com que as informações conflitantes do dialeto do mecanismo em uma visualização sejam substituídas pela nova definição. A palavra-chave `FORCE` é útil quando uma atualização em uma visualização do Catálogo de Dados resulta em definições de visualizações conflitantes entre os dialetos dos mecanismos existentes. Suponha que uma visualização do Catálogo de Dados tenha os dialetos do Athena e do Amazon Redshift e que a atualização resulte em um conflito com o Amazon Redshift na definição de visualização. Nesse caso, é possível usar a palavra-chave `FORCE` para permitir que a atualização seja concluída e marcar o dialeto do Amazon Redshift como obsoleto. Quando mecanismos marcados como obsoletos consultam a visualização, a consulta apresenta falhas. Os mecanismos lançam uma exceção para rejeitar resultados obsoletos. Para corrigir isso, atualize os dialetos obsoletos na visualização. **ADD** Adiciona um novo dialeto do mecanismo à visualização do Catálogo de Dados. O mecanismo especificado ainda não deve existir na visualização do Catálogo de Dados. **UPDATE** Atualiza um dialeto do mecanismo que já existe na visualização do Catálogo de Dados. **DROP** Descarta um dialeto do mecanismo existente de uma visualização do Catálogo de Dados. Após descartar um mecanismo de uma visualização do Catálogo de Dados, a visualização do Catálogo de Dados não poderá ser consultada pelo mecanismo que foi descartado. Outros dialetos do mecanismo na visualização ainda podem consultar a visualização. **DIALECT AS** Apresenta uma consulta SQL específica para o mecanismo. ## Exemplos ``` ALTER VIEW orders_by_date FORCE ADD DIALECT AS SELECT orderdate, sum(totalprice) AS price FROM orders GROUP BY orderdate ``` ``` ALTER VIEW orders_by_date FORCE UPDATE DIALECT AS SELECT orderdate, sum(totalprice) AS price FROM orders GROUP BY orderdate ``` ``` ALTER VIEW orders_by_date DROP DIALECT ``` # CREATE DATABASE Cria um banco de dados. O uso de `DATABASE` e `SCHEMA` é intercambiável. Eles significam a mesma coisa. **nota** Para ver um exemplo de como criar um banco de dados, criar uma tabela e executar uma consulta `SELECT` na tabela do Athena, consulte [Conceitos básicos](getting-started.md). ## Resumo ``` CREATE {DATABASE|SCHEMA} [IF NOT EXISTS] database_name [COMMENT 'database_comment'] [LOCATION 'S3_loc'] [WITH DBPROPERTIES ('property_name' = 'property_value') [, ...]] ``` Para obter restrições sobre nomes de bancos de dados no Athena, consulte [Nomear bancos de dados, tabelas e colunas](tables-databases-columns-names.md). ## Parâmetros **[IF NOT EXISTS]** Fará o erro ser suprimido se um banco de dados chamado `database_name` já existir. **[COMMENT database\$1comment]** Estabelece o valor de metadados para a propriedade de metadados interna chamada `comment` e o valor fornecido por você para `database_comment`. No AWS Glue, o conteúdo de `COMMENT` é gravado no campo `Description` das propriedades do banco de dados. **[LOCATION S3\$1loc]** Especifica o local onde arquivos de banco de dados e metastore existirão como `S3_loc`. O local deve ser um local do Amazon S3. **[WITH DBPROPERTIES ('property\$1name' = 'property\$1value') [, ...] ]** Permite especificar propriedades de metadados personalizados para a definição do banco de dados. ## Exemplos ``` CREATE DATABASE clickstreams; ``` ``` CREATE DATABASE IF NOT EXISTS clickstreams COMMENT 'Site Foo clickstream data aggregates' LOCATION 's3://amzn-s3-demo-bucket/clickstreams/' WITH DBPROPERTIES ('creator'='Jane D.', 'Dept.'='Marketing analytics'); ``` ## Visualizar as propriedades do banco de dados Para visualizar as propriedades de um banco de dados criado no AWSDataCatalog usando `CREATE DATABASE`, você pode usar o comando [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/get-database.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/get-database.html) da AWS CLI, como no seguinte exemplo: ``` aws glue get-database --name ``` Na saída do JSON, o resultado é semelhante ao seguinte: ``` { "Database": { "Name": "", "Description": "", "LocationUri": "s3://amzn-s3-demo-bucket", "Parameters": { "": "" }, "CreateTime": 1603383451.0, "CreateTableDefaultPermissions": [ { "Principal": { "DataLakePrincipalIdentifier": "IAM_ALLOWED_PRINCIPALS" }, "Permissions": [ "ALL" ] } ] } } ``` Para obter mais informações sobre a AWS CLI, consulte o [Manual do usuário da AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/). # CREATE TABLE Cria uma tabela com o nome e os parâmetros especificados por você. **nota** Esta página contém informações de referência resumidas. Para obter mais informações sobre como criar tabelas no Athena e um exemplo de instrução `CREATE TABLE`, consulte [Criar tabelas no Athena](creating-tables.md). Para ver um exemplo de como criar um banco de dados, criar uma tabela e executar uma consulta `SELECT` na tabela do Athena, consulte [Conceitos básicos](getting-started.md). ## Resumo ``` CREATE EXTERNAL TABLE [IF NOT EXISTS] [db_name.]table_name [(col_name data_type [COMMENT col_comment] [, ...] )] [COMMENT table_comment] [PARTITIONED BY (col_name data_type [COMMENT col_comment], ...)] [CLUSTERED BY (col_name, col_name, ...) INTO num_buckets BUCKETS] [ROW FORMAT row_format] [STORED AS file_format] [WITH SERDEPROPERTIES (...)] [LOCATION 's3://amzn-s3-demo-bucket/[folder]/'] [TBLPROPERTIES ( ['has_encrypted_data'='true | false',] ['encryption_option'='SSE_S3 | SSE_KMS | CSE_KMS',] ['kms_key'='aws_kms_key_arn',] ['classification'='aws_glue_classification',] property_name=property_value [, ...] ) ] ``` ## Parâmetros **EXTERNAL** Especifica que a tabela é baseada em um arquivo de dados subjacente existente no Amazon S3, no `LOCATION` que você especificar. Exceto ao criar tabelas do [Iceberg](querying-iceberg-creating-tables.md), use sempre a palavra-chave `EXTERNAL`. Se você usar `CREATE TABLE` sem a palavra-chave `EXTERNAL` para tabelas que não são do Iceberg, o Athena emitirá um erro. Quando você cria uma tabela externa, os dados referenciados devem estar em conformidade com o formato padrão ou o formato especificado por você com as cláusulas `ROW FORMAT`, `STORED AS` e `WITH SERDEPROPERTIES`. **[IF NOT EXISTS]** Este parâmetro verifica se já existe uma tabela com o mesmo nome. Se existir, o parâmetro retornará `TRUE` e o Amazon Athena cancelará a ação `CREATE TABLE`. Como o cancelamento ocorre antes que o Athena chame o catálogo de dados, ele não emite um evento AWS CloudTrail. **[db\$1name.]table\$1name** Especifica um nome para a tabela a ser criada. O parâmetro `db_name` opcional especifica o banco de dados no qual a tabela existe. Se omitido, o banco de dados atual será assumido. Se o nome da tabela inclui números, coloque `table_name` entre aspas, por exemplo `"table123"`. Se `table_name` começar com um sublinhado, use acentos graves, por exemplo, ``_mytable``. Os caracteres especiais (que não sejam sublinhado) não são compatíveis. Os nomes de tabela do Athena não diferenciam maiúsculas de minúsculas. No entanto, se você trabalhar com o Apache Spark, o Spark exigirá nomes de tabela em letras minúsculas. Para restrições sobre nomes de tabelas no Athena, consulte [Nomear bancos de dados, tabelas e colunas](tables-databases-columns-names.md). **[ ( col\$1name data\$1type [COMMENT col\$1comment] [, ...] ) ]** Especifica o nome de cada coluna a ser criada, além do tipo de dados da coluna. Os nomes de coluna não permitem caracteres especiais além de sublinhado `(_)`. Se `col_name` começar com um sublinhado, coloque o nome da coluna entre acentos graves, por exemplo ``_mycolumn``. Para restrições sobre nomes de colunas no Athena, consulte [Nomear bancos de dados, tabelas e colunas](tables-databases-columns-names.md). O valor `data_type` pode ser qualquer um dos seguintes: + `boolean` – os valores são `true` e `false`. + `tinyint`: um inteiro com sinal de 8 bits no formato de complemento de dois, com um valor mínimo de -2^7 e um valor máximo de 2^7-1. + `smallint`: um inteiro com sinal de 16 bits no formato de complemento de dois, com um valor mínimo de -2^15 e um valor máximo de 2^15-1. + `int`: nas consultas em Data Definition Language (DDL), como `CREATE TABLE`, use a palavra-chave `int` para representar um número inteiro. Em outras consultas, use a palavra-chave `integer`, em que `integer` é representado por um valor com sinal de 32 bits no formato de complemento de dois, com um valor mínimo de -2^31 e um valor máximo de 2^31-1. No driver JDBC, `integer` é retornado para garantir a compatibilidade com os aplicativos de análise de negócios. + `bigint`: um inteiro com sinal de 64 bits no formato de complemento de dois, com um valor mínimo de -2^63 e um valor máximo de 2^63-1. + `double`: um número com sinal de ponto flutuante de precisão dupla de 64 bits. O intervalo é de 4.94065645841246544e-324d a 1.79769313486231570e\$1308d, positivo ou negativo. `double` segue o padrão para aritmética de ponto flutuante do IEEE (IEEE 754). + `float`: um número com sinal de ponto flutuante de precisão única de 32 bits. O intervalo é de 1.40129846432481707e-45 a 3.40282346638528860e\$138, positivo ou negativo. `float` segue o padrão para aritmética de ponto flutuante do IEEE (IEEE 754). Equivalente a `real` no Presto. No Athena, use `float` nas instruções DDL, como `CREATE TABLE`, e `real` nas funções SQL, como `SELECT CAST`. O crawler do AWS Glue retorna os valores em `float`, e o Athena converte os tipos `real` e `float` internamente (leia as notas de release [5 de junho de 2018](release-notes.md#release-note-2018-06-05)). + `decimal [ (precision, scale) ]`, onde `precision` é o número total de dígitos e `scale` (opcional) é o número de dígitos na parte fracionada, o padrão é 0. Por exemplo, use estas definições de tipo: `decimal(11,5)`, `decimal(15)`. O valor máximo para *precisão* é 38 e o valor máximo para *escala* é 38. Para especificar valores decimais como literais, como ao selecionar filas com um valor decimal específico em uma expressão de consulta DDL, especifique a definição de tipo `decimal` e liste o valor decimal como um literal (em aspas simples) na consulta, como neste exemplo: `decimal_value = decimal '0.12'`. + `char` – os dados de caractere de comprimento fixo, com um tamanho especificado entre 1 e 255, como `char(10)`. Para obter mais informações, consulte [CHAR Hive data type](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types#LanguageManualTypes-char) (Tipo de dado CHAR do Hive). + `varchar` – os dados de caractere de comprimento variável, com um tamanho especificado entre 1 e 65535, como `varchar(10)`. Para obter mais informações, consulte [VARCHAR Hive data type](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types#LanguageManualTypes-varchar) (Tipo de dado VARCHAR do Hive). + `string`: um literal de string entre aspas simples ou duplas. **nota** Os tipos de dados que não são de string não podem ser convertidos em `string` no Athena. Em vez disso, converta-os em `varchar`. + `binary`: (para dados em Parquet) + `date` – Uma data no formato ISO, como `YYYY-MM-DD`. Por exemplo, `date '2008-09-15'`. Uma exceção é o OpenCSVSerDe, que usa o número de dias decorridos desde 1° de janeiro de 1970. Para obter mais informações, consulte [Open CSV SerDe para processamento de CSV](csv-serde.md). + `timestamp`: instante de data e hora em um formato compatível com [https://docs.oracle.com/javase/8/docs/api/java/sql/Timestamp.html](https://docs.oracle.com/javase/8/docs/api/java/sql/Timestamp.html) até uma resolução máxima de milissegundos, como `yyyy-MM-dd HH:mm:ss[.f...]`. Por exemplo, `timestamp '2008-09-15 03:04:05.324'`. Uma exceção é o OpenCSVSerDe, que usa os dados de `TIMESTAMP` no formato numérico UNIX (por exemplo, `1579059880000`). Para obter mais informações, consulte [Open CSV SerDe para processamento de CSV](csv-serde.md). + `array` < data\$1type > + `map` < primitive\$1type, data\$1type > + `struct` < col\$1name : data\$1type [comment col\$1comment] [, ...] > **[COMMENT table\$1comment]** Cria a propriedade da tabela `comment` e a preenche com o `table_comment` especificado por você. **[PARTITIONED BY (col\$1name data\$1type [ COMMENT col\$1comment ], ... ) ]** Cria uma tabela particionada com uma ou mais colunas de partição que tenham `col_name`, `data_type` e `col_comment` especificados. A tabela pode ter uma ou mais partições, que consistem em uma combinação distinta de nome e valor de coluna. Um diretório de dados à parte é criado para cada combinação especificada, o que pode melhorar a performance da consulta em algumas circunstâncias. As colunas particionadas não existem na própria tabela de dados. Se você usar um valor para `col_name` que é o mesmo valor usado na coluna da tabela, obterá um erro. Para obter mais informações, consulte [Particionar dados](partitions.md). Depois de criar uma tabela com partições, execute uma consulta que consista na cláusula [MSCK REPAIR TABLE](msck-repair-table.md) para atualizar metadados de partição, por exemplo, `MSCK REPAIR TABLE cloudfront_logs;`. Para partições que não são compatíveis com o Hive, use o [ALTER TABLE ADD PARTITION](alter-table-add-partition.md) a fim de carregar as partições para que você consiga consultar os dados. **[CLUSTERED BY (col\$1name, col\$1name, ...) INTO num\$1buckets BUCKETS]** Divide, com ou sem particionamento, os dados nas colunas `col_name` especificadas em subconjuntos de dados chamados *buckets*. O parâmetro `num_buckets` especifica o número de buckets que serão criados. A criação de buckets pode melhorar a performance de algumas consultas em grandes conjuntos de dados. **[ROW FORMAT row\$1format]** Especifica o formato de linha da tabela e os dados de origem subjacente, se aplicável. Para `row_format`, você pode especificar um ou mais delimitadores com a cláusula `DELIMITED` ou, como alternativa, usar a cláusula `SERDE` conforme descrito abaixo. Se `ROW FORMAT` for omitido ou `ROW FORMAT DELIMITED` for especificado, um SerDe nativo será usado. + [DELIMITED FIELDS TERMINATED BY char [ESCAPED BY char]] + [DELIMITED COLLECTION ITEMS TERMINATED BY char] + [MAP KEYS TERMINATED BY char] + [LINES TERMINATED BY char] + [NULL DEFINED AS char] Disponível somente com o Hive 0.13 e quando o formato de arquivo em STORED AS (ARMAZENADO COMO) for `TEXTFILE`. **--OU--** + SERDE 'serde\$1name' [WITH SERDEPROPERTIES ("property\$1name" = "property\$1value", "property\$1name" = "property\$1value" [, ...] )] O `serde_name` indica o SerDe a ser usado. A cláusula `WITH SERDEPROPERTIES` permite fornecer uma ou mais propriedades personalizadas permitidas pelo SerDe. **[STORED AS formato do arquivo]** Especifica o formato de arquivo para dados da tabela. Se omitido, `TEXTFILE` será o padrão. As opções de `file_format` são: + SEQUENCEFILE + TEXTFILE + RCFILE + ORC + PARQUET + AVRO + ION + INPUTFORMAT input\$1format\$1classname OUTPUTFORMAT output\$1format\$1classname **[LOCATION 's3://amzn-s3-demo-bucket/[folder]/']** Especifica o local dos dados subjacentes no Amazon S3 dos quais a tabela é criada. O caminho do local deve ser um nome de bucket ou um nome de bucket e uma ou mais pastas. Se você estiver usando partições, especifique a raiz dos dados particionados. Para obter mais informações sobre a localização da tabela, consulte [Especificar um local de tabela no Amazon S3](tables-location-format.md). Para obter informações sobre formatos de dados e permissões, consulte [Considerações sobre o Amazon S3](creating-tables.md#s3-considerations). Use uma barra à direita para a pasta ou o bucket. Não use nomes de arquivo ou caracteres glob. **Use:** `s3://amzn-s3-demo-bucket/` `s3://amzn-s3-demo-bucket/folder/` `s3://amzn-s3-demo-bucket/folder/anotherfolder/` **Não use:** `s3://amzn-s3-demo-bucket` `s3://amzn-s3-demo-bucket/*` `s3://amzn-s3-demo-bucket/mydatafile.dat` **[TBLPROPERTIES ( ['has\$1encrypted\$1data'='true \$1 false',] ['encryption\$1option'='SSE\$1S3 \$1 SSE\$1KMS \$1 CSE\$1KMS',] ['kms\$1key'='aws\$1kms\$1key\$1arn',] ['classification'='classification\$1value',] property\$1name=property\$1value [, ...] ) ]** Especifica pares de chave/valor de metadados personalizados para a definição da tabela, além das propriedades da tabela predefinidas, como `"comment"`. **has\$1encrypted\$1data**: o Athena tem uma propriedade integrada, `has_encrypted_data`. Defina essa propriedade como `true` para indicar que o conjunto de dados subjacente especificado por `LOCATION` está criptografado com CSE-KMS. Se omitido e se as configurações do grupo de trabalho não substituírem as configurações do lado do cliente, a pressuposição será `false`. Se omitido ou definido como `false` quando os dados subjacentes estiverem criptografados, a consulta resultará em um erro. Para obter mais informações, consulte [Criptografia em repouso](encryption.md). **encryption\$1option**: defina essa propriedade como `SSE_S3`, `SSE_KMS` ou `CSE_KMS` para indicar o nível mais alto de criptografia usado no conjunto de dados subjacente especificado por `LOCATION`. Para obter mais informações, consulte [Criptografia em repouso](encryption.md). **kms\$1key**: defina essa propriedade como o ARN da chave do AWS KMS usada para criptografar e descriptografar arquivos de dados da tabela. O Athena usa essa chave para criptografar arquivos de dados de tabela ao gravar com criptografia `SSE_KMS` ou `CSE_KMS` e para descriptografar arquivos de dados de tabela criptografados com CSE-KMS. Essa propriedade somente é necessária quando `encryption_option` é definido como `SSE_KMS` ou `CSE_KMS`. Para obter mais informações, consulte [Criptografia em repouso](encryption.md). **classificação**: as tabelas criadas para o Athena no console do CloudTrail adicionam `cloudtrail` como um valor para a propriedade `classification`. Para executar trabalhos ETL, o AWS Glue requer a criação de uma tabela com a propriedade `classification` para indicar o tipo de dados do AWS Glue como `csv`, `parquet`, `orc`, `avro` ou `json`. Por exemplo, `'classification'='csv'`. Os trabalhos ETL falharão se você não especificar essa propriedade. Você poderá especificá-la mais tarde usando o console do AWS Glue, a API ou a CLI. Para obter mais informações, consulte [Criação de tabelas para trabalhos de ETL](schema-classifier.md) e [Criar trabalhos no AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/author-job.html) no *Guia do desenvolvedor do AWS Glue*. **compression\$1level**: a propriedade `compression_level` especifica o nível de compactação a ser usado. Essa propriedade se aplica apenas à compactação ZSTD. Os valores possíveis são de 1 a 22. O valor padrão é 3. Para obter mais informações, consulte [Usar níveis de compactação ZSTD](compression-support-zstd-levels.md). Para obter mais informações sobre outras propriedades de tabelas, consulte [ALTER TABLE SET TBLPROPERTIES](alter-table-set-tblproperties.md). ## Exemplos A instrução de exemplo `CREATE TABLE` a seguir cria uma tabela com base em dados de planetas separados por tabulações armazenados no Amazon S3. ``` CREATE EXTERNAL TABLE planet_data ( planet_name string, order_from_sun int, au_to_sun float, mass float, gravity_earth float, orbit_years float, day_length float ) ROW FORMAT DELIMITED FIELDS TERMINATED BY '\t' STORED AS TEXTFILE LOCATION 's3://amzn-s3-demo-bucket/tsv/' ``` Observe os seguintes pontos: + A cláusula `ROW FORMAT DELIMITED` indica que os dados são delimitados por um caractere específico. + A cláusula `FIELDS TERMINATED BY '\t'` especifica que os campos nos dados do TSV sejam separados pelo caractere de tabulação ('\$1t'). + A cláusula `STORED AS TEXTFILE` indica que os dados sejam armazenados como arquivos de texto simples no Amazon S3. Para consultar os dados, você pode usar uma instrução simples `SELECT` como a seguinte: ``` SELECT * FROM planet_data ``` Para usar o exemplo para criar sua própria tabela TSV no Athena, substitua os nomes das tabelas e colunas pelos nomes e tipos de dados de sua própria tabela e colunas e atualize a cláusula `LOCATION` para apontar para o caminho do Amazon S3 em que seus arquivos TSV estão armazenados. Para obter mais informações sobre como criar tabelas, consulte [Criar tabelas no Athena](creating-tables.md). # CREATE TABLE AS Cria uma tabela preenchida com os resultados de uma consulta [SELECT](select.md). Para criar uma tabela vazia, use [CREATE TABLE](create-table.md). `CREATE TABLE AS` combina uma instrução DDL `CREATE TABLE` com uma instrução DML `SELECT` e, portanto, tecnicamente contém DDL e DML. Observe que, embora `CREATE TABLE AS` esteja agrupado aqui com outras instruções DDL, as consultas CTAS no Athena são tratadas como DML para fins de cotas de serviço. Para obter informações sobre as cotas de serviço do Athena, consulte [Service Quotas](service-limits.md). **nota** Para instruções CTAS, a configuração esperada do proprietário do bucket não se aplica ao local da tabela de destino no Amazon S3. A configuração esperada do proprietário do bucket se aplica somente ao local de saída do Amazon S3 que você especificar para os resultados da consulta do Athena. Para ter mais informações, consulte [Especificar um local para resultados de consultas com uso do console do Athena](query-results-specify-location-console.md). Para obter outras informações sobre `CREATE TABLE AS` que não fazem parte do escopo deste tópico de referência, consulte [Criar uma tabela com base em resultados de consultas (CTAS)](ctas.md). **Topics** + [Resumo](#synopsis) + [Propriedades da tabela CTAS](#ctas-table-properties) + [Exemplos](#ctas-table-examples) ## Resumo ``` CREATE TABLE table_name [ WITH ( property_name = expression [, ...] ) ] AS query [ WITH [ NO ] DATA ] ``` Em que: **COM ( property\$1name = expression [, ...] )** Uma lista de propriedades opcionais da tabela CTAS, algumas das quais são específicas do formato de armazenamento de dados. Consulte [Propriedades da tabela CTAS](#ctas-table-properties). **consulta** A consulta [SELECT](select.md) que é usada para criar uma tabela. Se você planeja criar uma consulta com partições, especifique os nomes das colunas particionadas por último na lista de colunas na `SELECT` instrução. **[ WITH [ NO ] DATA ]** Se `WITH NO DATA` for usado, uma tabela vazia com o mesmo esquema da tabela original será criada. **nota** Para incluir cabeçalhos de coluna na saída do resultado da consulta, você pode usar uma consulta `SELECT` simples em vez de uma consulta CTAS. Você pode recuperar os resultados no local dos resultados da consulta ou baixá-los diretamente usando o console do Athena. Para ter mais informações, consulte [Trabalhar com resultados de consultas e consultas recentes](querying.md). ## Propriedades da tabela CTAS Cada tabela CTAS no Athena tem uma lista de propriedades opcionais que você especifica usando `WITH (property_name = expression [, ...] )`. Para obter mais informações sobre como usar esses parâmetros, consulte [Exemplos de consultas CTAS](ctas-examples.md). ** `WITH (property_name = expression [, ...], )` ** `table_type = ['HIVE', 'ICEBERG']` Opcional. O padrão é `HIVE`. Especifica o tipo de tabela da tabela resultante. Exemplo: ``` WITH (table_type ='ICEBERG') ``` `external_location = [location]` Como as tabelas do Iceberg não são externas, essa propriedade não se aplicará a elas. Para definir o local raiz de uma tabela do Iceberg em uma instrução CTAS, use a propriedade `location`, que será descrita posteriormente nesta seção. Opcional. O local no qual o Athena salvará sua consulta CTAS no Amazon S3. Exemplo: ``` WITH (external_location ='s3://amzn-s3-demo-bucket/tables/parquet_table/') ``` O Athena não usa o mesmo caminho duas vezes para os resultados das consultas. Se você especificar o local manualmente, verifique se o local especificado no Amazon S3 não contém dados. O Athena nunca tenta excluir os dados. Para usar o mesmo local novamente, exclua os dados manualmente. Caso contrário, a consulta CTAS falhará. Se você executar uma consulta CTAS que especifica um `external_location` em um grupo de trabalho que [impõe um local para os resultados de consultas](workgroups-settings-override.md), a consulta falhará com uma mensagem de erro. Para ver o local dos resultados de consultas especificado para o grupo de trabalho, [consulte os detalhes do grupo de trabalho](viewing-details-workgroups.md). Se o grupo de trabalho substituir a configuração de local dos resultados das consultas do lado do cliente, o Athena criará sua tabela no seguinte local: ``` s3://amzn-s3-demo-bucket/tables/query-id/ ``` Se você não usar a propriedade `external_location` para especificar um local, e o grupo de trabalho não substituir as configurações do lado do cliente, o Athena usará a [configuração do lado do cliente](query-results-specify-location-console.md) de local dos resultados das consultas para criar sua tabela no seguinte local: ``` s3://amzn-s3-demo-bucket/Unsaved-or-query-name/year/month/date/tables/query-id/ ``` `is_external = [boolean]` Opcional. Indica se a tabela corresponde a uma tabela externa. O padrão é true. Para tabelas do Iceberg, deve ser definido como “false” (falso). Exemplo: ``` WITH (is_external = false) ``` `location = [location]` Obrigatório para tabelas do Iceberg. Especifica o local raiz da tabela do Iceberg que será criada a partir dos resultados da consulta. Exemplo: ``` WITH (location ='s3://amzn-s3-demo-bucket/tables/iceberg_table/') ``` `field_delimiter = [delimiter]` Opcionais e específicos para formatos de armazenamento físico de dados com base em texto. O delimitador de campo de caractere único para arquivos em CSV, TSV e de texto. Por exemplo, `WITH (field_delimiter = ',')`. Atualmente, os delimitadores de campo de vários caracteres não são permitidos em consultas CTAS. Se você não especificar um delimitador do campo, `\001` será usado por padrão. `format = [storage_format]` O formato de armazenamento dos resultados de consultas CTAS, como `ORC`, `PARQUET`, `AVRO`, `JSON`, `ION` ou `TEXTFILE`. Para tabelas do Iceberg, os formatos permitidos são `ORC`, `PARQUET` e `AVRO`. Se for omitido, `PARQUET` é usado por padrão. O nome deste parâmetro, `format`, deve estar listado em minúsculas, ou sua consulta CTAS falhará. Exemplo: ``` WITH (format = 'PARQUET') ``` `bucketed_by = ARRAY[ column_name[,…], bucket_count = [int] ]` Essa propriedade não se aplica para tabelas do Iceberg. Para tabelas do Iceberg, use o particionamento com transformação de bucket. Uma lista matriz de buckets para dados do bucket. Se omitida, o Athena não armazenará os dados dessa consulta em bucket. `bucket_count = [int]` Essa propriedade não se aplica para tabelas do Iceberg. Para tabelas do Iceberg, use o particionamento com transformação de bucket. O número de buckets para armazenar seus dados em um bucket. Se omitido, o Athena não armazenará os dados em bucket. Exemplo: ``` CREATE TABLE bucketed_table WITH ( bucketed_by = ARRAY[column_name], bucket_count = 30, format = 'PARQUET', external_location ='s3://amzn-s3-demo-bucket/tables/parquet_table/' ) AS SELECT * FROM table_name ``` `partitioned_by = ARRAY[ col_name[,…] ]` Essa propriedade não se aplica para tabelas do Iceberg. Para usar transformações de partição para tabelas do Iceberg, use a propriedade `partitioning`, que será descrita posteriormente nesta seção. Opcional. Uma lista matriz de colunas pela qual a tabela CTAS será particionada. Verifique se os nomes das colunas particionadas estão listados por último na lista de colunas da instrução `SELECT`. `partitioning = ARRAY[partition_transform, ...]` Opcional. Especifica o particionamento da tabela do Iceberg que será criada. O Iceberg é compatível com uma ampla variedade de transformações e evoluções de partições. As transformações de partição estão resumidas na tabela a seguir. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/create-table-as.html) Exemplo: ``` WITH (partitioning = ARRAY['month(order_date)', 'bucket(account_number, 10)', 'country'])) ``` `optimize_rewrite_min_data_file_size_bytes = [long]` Opcional. Configuração específica de otimização de dados. Arquivos menores que o valor especificado são incluídos para otimização. O padrão é 0,75 vezes o valor de `write_target_data_file_size_bytes`. Essa propriedade se aplica apenas a tabelas do Iceberg. Para ter mais informações, consulte [Otimizar tabelas do Iceberg](querying-iceberg-data-optimization.md). Exemplo: ``` WITH (optimize_rewrite_min_data_file_size_bytes = 402653184) ``` `optimize_rewrite_max_data_file_size_bytes = [long]` Opcional. Configuração específica de otimização de dados. Arquivos maiores que o valor especificado são incluídos para otimização. O padrão é 1,8 vezes o valor de `write_target_data_file_size_bytes`. Essa propriedade se aplica apenas a tabelas do Iceberg. Para ter mais informações, consulte [Otimizar tabelas do Iceberg](querying-iceberg-data-optimization.md). Exemplo: ``` WITH (optimize_rewrite_max_data_file_size_bytes = 966367641) ``` `optimize_rewrite_data_file_threshold = [int]` Opcional. Configuração específica de otimização de dados. Se houver menos arquivos de dados que exigem otimização do que o limite fornecido, os arquivos não serão regravados. Isso permite acumular mais arquivos de dados para produzir arquivos mais próximos do tamanho de destino e ignorar a computação desnecessária para gerar economia de custos. O padrão é 5. Essa propriedade se aplica apenas a tabelas do Iceberg. Para ter mais informações, consulte [Otimizar tabelas do Iceberg](querying-iceberg-data-optimization.md). Exemplo: ``` WITH (optimize_rewrite_data_file_threshold = 5) ``` `optimize_rewrite_delete_file_threshold = [int]` Opcional. Configuração específica de otimização de dados. Se houver menos arquivos de exclusão associados a um arquivo de dados do que o limite, o arquivo de dados não será regravado. Isso permite acumular mais arquivos de exclusão para cada arquivo de dados a fim de gerar economia de custos. O padrão é 2. Essa propriedade se aplica apenas a tabelas do Iceberg. Para ter mais informações, consulte [Otimizar tabelas do Iceberg](querying-iceberg-data-optimization.md). Exemplo: ``` WITH (optimize_rewrite_delete_file_threshold = 2) ``` `vacuum_min_snapshots_to_keep = [int]` Opcional. Configuração específica para vácuo. O número mínimo de snapshots mais recentes a serem retidos. O padrão é um. Essa propriedade se aplica apenas a tabelas do Iceberg. Para ter mais informações, consulte [VACUUM](vacuum-statement.md). A propriedade `vacuum_min_snapshots_to_keep` requer a versão 3 do mecanismo do Athena. Exemplo: ``` WITH (vacuum_min_snapshots_to_keep = 1) ``` `vacuum_max_snapshot_age_seconds = [long]` Opcional. Configuração específica para vácuo. Um período, em segundos, que representa o tempo pelo qual os snapshots serão retidos. O padrão é 432 mil (5 dias). Essa propriedade se aplica apenas a tabelas do Iceberg. Para ter mais informações, consulte [VACUUM](vacuum-statement.md). A propriedade `vacuum_max_snapshot_age_seconds` requer a versão 3 do mecanismo do Athena. Exemplo: ``` WITH (vacuum_max_snapshot_age_seconds = 432000) ``` `write_compression = [compression_format]` O tipo de compactação a ser usado para qualquer formato de armazenamento que permita que a compactação seja especificada. O valor `compression_format` especifica a compactação a ser usada quando os dados são gravados na tabela. Você pode especificar a compactação para os formatos de arquivo `TEXTFILE`, `JSON`, `PARQUET` e `ORC`. Por exemplo, se a propriedade `format` especificar `PARQUET` como o formato de armazenamento, o valor para `write_compression` especificará o formato de compactação para Parquet. Nesse caso, especificar um valor para `write_compression` é equivalente a especificar um valor para `parquet_compression`. Por exemplo, se a propriedade `format` especificar `ORC` como o formato de armazenamento, o valor para `write_compression` especificará o formato de compactação para ORC. Nesse caso, especificar um valor para `write_compression` é equivalente a especificar um valor para `orc_compression`. Não é possível especificar várias propriedades da tabela de formato de compactação na mesma consulta CTAS. Por exemplo, não é possível especificar `write_compression` e `parquet_compression` na mesma consulta. O mesmo se aplica a `write_compression` e `orc_compression`. Para obter mais informações sobre os tipos de compactação suportados para cada formato de arquivo, consulte [Usar compactação no Athena](compression-formats.md). `orc_compression = [compression_format]` O tipo de compactação a ser usado para o formato de arquivo `ORC` quando dados `ORC` são gravados na tabela. Por exemplo, `WITH (orc_compression = 'ZLIB')`. As partes dentro do arquivo `ORC` (exceto o `ORC` Postscript) são compactadas usando a compactação que você especificar. Se não especificada, a compactação ZLIB será usada por padrão para `ORC`. Para consistência, recomendamos que você use a propriedade `write_compression` em vez de `orc_compression`. Use a propriedade `format` para especificar o formato de armazenamento como `ORC` e, em seguida, use a propriedade `write_compression` para especificar o formato de compactação que `ORC` usará. `parquet_compression = [compression_format]` O tipo de compactação a ser usado para o formato de arquivo Parquet quando os dados do Parquet são gravados na tabela. Por exemplo, `WITH (parquet_compression = 'SNAPPY')`. Essa compactação é aplicada a blocos de colunas em arquivos Parquet. Se não especificada, a compactação GZIP será usada por padrão para Parquet. Para consistência, recomendamos que você use a propriedade `write_compression` em vez de `parquet_compression`. Use a propriedade `format` para especificar o formato de armazenamento como `PARQUET` e, em seguida, use a propriedade `write_compression` para especificar o formato de compactação que `PARQUET` usará. `compression_level = [compression_level]` O nível de compressão a ser usado. Essa propriedade se aplica apenas à compressão ZSTD. Os valores possíveis são de 1 a 22. O valor padrão é 3. Para ter mais informações, consulte [Usar níveis de compactação ZSTD](compression-support-zstd-levels.md). ## Exemplos Para obter exemplos de consultas CTAS, consulte os seguintes recursos. + [Exemplos de consultas CTAS](ctas-examples.md) + [Usar CTAS e INSERT INTO para ETL e análise de dados](ctas-insert-into-etl.md) + [Use CTAS statements with Amazon Athena to reduce cost and improve performance](https://aws.amazon.com/blogs/big-data/using-ctas-statements-with-amazon-athena-to-reduce-cost-and-improve-performance/) (Usar instruções CTAS com o Amazon Athena para reduzir custos e melhorar a performance) + [Usar CTAS e INSERT INTO para resolver o limite de 100 partições](ctas-insert-into.md) # CREATE VIEW e da CREATE PROTECTED MULTI DIALECT VIEW Uma visualização é uma tabela lógica que pode ser referenciada por futuras consultas. As visualizações não contêm todos os dados e não gravam dados. Em vez disso, a consulta especificada pela exibição é executada sempre que você fizer referência à exibição por outra consulta. + `CREATE VIEW` cria uma visualização do Athena a partir de uma consulta `SELECT` especificada. As visualizações do Athena funcionam dentro do Athena. Para obter mais informações sobre visualizações do Athena, consulte [Trabalhar com visualizações](views.md). + `CREATE PROTECTED MULTI DIALECT VIEW` cria uma visualização do AWS Glue Data Catalog no AWS Glue Data Catalog. As visualizações do AWS Glue Data Catalog fornecem uma visualização única e comum entre os Serviços da AWS como o Amazon Athena e o Amazon Redshift. Para obter mais informações sobre visualizações do AWS Glue Data Catalog, consulte [Usar visualizações do Catálogo de Dados no Athena](views-glue.md). ## CREATE VIEW Cria uma visualização para uso no Athena. ### Resumo ``` CREATE [ OR REPLACE ] VIEW view_name AS query ``` A cláusula `OR REPLACE` opcional permite atualizar a exibição existente substituindo-a Para obter mais informações, consulte [Criar visualizações](views-console.md#creating-views). ### Exemplos Para criar uma exibição `test` a partir da tabela `orders`, use uma consulta semelhante à seguinte: ``` CREATE VIEW test AS SELECT orderkey, orderstatus, totalprice / 2 AS half FROM orders; ``` Para criar uma exibição `orders_by_date` a partir da tabela `orders`, use a seguinte consulta: ``` CREATE VIEW orders_by_date AS SELECT orderdate, sum(totalprice) AS price FROM orders GROUP BY orderdate; ``` Para atualizar uma exibição existente, use um exemplo semelhante ao seguinte: ``` CREATE OR REPLACE VIEW test AS SELECT orderkey, orderstatus, totalprice / 4 AS quarter FROM orders; ``` Para obter mais informações sobre o uso de visualizações do Athena, consulte [Trabalhar com visualizações](views.md). ## CREATE PROTECTED MULTI DIALECT VIEW Cria uma visualização do AWS Glue Data Catalog no AWS Glue Data Catalog. Uma visualização do Catálogo de Dados corresponde a um esquema de visualização única que funciona entre o Athena e outros mecanismos de SQL, como o Amazon Redshift e o Amazon EMR. ### Sintaxe ``` CREATE [ OR REPLACE ] PROTECTED MULTI DIALECT VIEW view_name SECURITY DEFINER [ SHOW VIEW JSON ] AS query ``` **OR REPLACE** (Opcional) Atualiza a visualização existente substituindo-a. Uma visualização do Catálogo de Dados não poderá ser substituída se dialetos SQL de outros mecanismos estiverem presentes na visualização. Se o mecanismo de chamada tiver o único dialeto SQL presente na visualização, a visualização poderá ser substituída. **PROTECTED** Palavra-chave obrigatória. Especifica que a visualização está protegida contra vazamentos de dados. As visualizações do Catálogo de Dados podem ser criadas somente como uma visualização `PROTECTED`. **MULTI DIALECT** Especifica que a visualização oferece suporte aos dialetos SQL de diferentes mecanismos de consulta e, portanto, que ela pode ser lida por esses mecanismos. **SECURITY DEFINER** Especifica que a semântica do programador está em vigor para essa visualização. A semântica do programador significa que as permissões de leitura efetivas nas tabelas subjacentes pertencem à entidade principal ou ao perfil que definiu a visualização, e não à entidade principal que executa a leitura. **SHOW VIEW JSON** (Opcional) Retorna o JSON para a especificação da visualização do Catálogo de Dados sem realmente criar uma visualização. Essa opção “dry-run” é útil quando você deseja validar o SQL para a visualização e retornar os metadados da tabela que serão usados pelo AWS Glue. ### Exemplo O exemplo apresentado a seguir cria a visualização `orders_by_date` do Catálogo de Dados com base em uma consulta na tabela `orders`. ``` CREATE PROTECTED MULTI DIALECT VIEW orders_by_date SECURITY DEFINER AS SELECT orderdate, sum(totalprice) AS price FROM orders WHERE order_city = 'SEATTLE' GROUP BY orderdate ``` Para obter mais informações sobre o uso de visualizações do AWS Glue Data Catalog, consulte [Usar visualizações do Catálogo de Dados no Athena](views-glue.md). # DESCRIBE Mostra uma ou mais colunas, inclusive de partição, da tabela especificada. Esse comando é útil para examinar os atributos de colunas complexas. ## Resumo ``` DESCRIBE [EXTENDED | FORMATTED] [db_name.]table_name [PARTITION partition_spec] [col_name ( [.field_name] | [.'$elem$'] | [.'$key$'] | [.'$value$'] )] ``` **Importante** A sintaxe para essa declaração é `DESCRIBE table_name`, não `DESCRIBE TABLE table_name`. O uso da última sintaxe resulta na mensagem de erro FAILED: SemanticException [Error 10001]: Table not found table (FALHA: SemanticException [Erro 10001]: Tabela não encontrada). ## Parâmetros **[EXTENDED \$1 FORMATTED]** Determina o formato da saída. A omissão desses parâmetros mostra nomes de colunas e os tipos de dados correspondentes, incluindo colunas de partição, em formato tabular. Especificando `FORMATTED` não só mostra nomes de colunas e tipos de dados em formato tabular, mas também traz informações detalhadas de tabela e armazenamento. `EXTENDED` mostra informações de coluna e tipos de dados em formato tabular, além de metadados detalhados para a tabela no formato serializado Thrift. Esse formato é menos legível e ajuda principalmente na depuração. **[PARTITION partition\$1spec]** Se incluído, lista os metadados para a partição especificada por `partition_spec`, onde `partition_spec` está no formato `(partition_column = partition_col_value, partition_column = partition_col_value, ...)`. **[col\$1name ( [.field\$1name] \$1 [.'\$1elem\$1'] \$1 [.'\$1key\$1'] \$1 [.'\$1value\$1'] )\$1 ]** Especifica a coluna e os atributos a serem examinados. Você pode especificar `.field_name` para um elemento de uma struct, `'$elem$'` para um elemento de matriz, `'$key$'` para uma chave de mapa e `'$value$'` para um valor de mapa. Você pode especificar isso de maneira recursiva para explorar mais a coluna complexa. ### Exemplos ``` DESCRIBE orders ``` ``` DESCRIBE FORMATTED mydatabase.mytable PARTITION (part_col = 100) columnA; ``` A consulta e a saída a seguir mostram informações de coluna e tipos de dados de uma tabela de `impressions` baseada em dados de amostra do Amazon EMR. ``` DESCRIBE impressions ``` ``` requestbegintime string from deserializer adid string from deserializer impressionid string from deserializer referrer string from deserializer useragent string from deserializer usercookie string from deserializer ip string from deserializer number string from deserializer processid string from deserializer browsercokie string from deserializer requestendtime string from deserializer timers struct from deserializer threadid string from deserializer hostname string from deserializer sessionid string from deserializer dt string # Partition Information # col_name data_type comment dt string ``` Os exemplos de consulta e saída a seguir mostram o resultado da mesma tabela quando a opção `FORMATTED` é usada. ``` DESCRIBE FORMATTED impressions ``` ``` requestbegintime string from deserializer adid string from deserializer impressionid string from deserializer referrer string from deserializer useragent string from deserializer usercookie string from deserializer ip string from deserializer number string from deserializer processid string from deserializer browsercokie string from deserializer requestendtime string from deserializer timers struct from deserializer threadid string from deserializer hostname string from deserializer sessionid string from deserializer dt string # Partition Information # col_name data_type comment dt string # Detailed Table Information Database: sampledb Owner: hadoop CreateTime: Thu Apr 23 02:55:21 UTC 2020 LastAccessTime: UNKNOWN Protect Mode: None Retention: 0 Location: s3://us-east-1.elasticmapreduce/samples/hive-ads/tables/impressions Table Type: EXTERNAL_TABLE Table Parameters: EXTERNAL TRUE transient_lastDdlTime 1587610521 # Storage Information SerDe Library: org.openx.data.jsonserde.JsonSerDe InputFormat: org.apache.hadoop.mapred.TextInputFormat OutputFormat: org.apache.hadoop.hive.ql.io.IgnoreKeyTextOutputFormat Compressed: No Num Buckets: -1 Bucket Columns: [] Sort Columns: [] Storage Desc Params: paths requestbegintime, adid, impressionid, referrer, useragent, usercookie, ip serialization.format 1 ``` Os exemplos de consulta e saída a seguir mostram o resultado da mesma tabela quando a opção `EXTENDED` é usada. As informações detalhadas da tabela são geradas em uma única linha, mas foram formatadas aqui para facilitar a leitura. ``` DESCRIBE EXTENDED impressions ``` ``` requestbegintime string from deserializer adid string from deserializer impressionid string from deserializer referrer string from deserializer useragent string from deserializer usercookie string from deserializer ip string from deserializer number string from deserializer processid string from deserializer browsercokie string from deserializer requestendtime string from deserializer timers struct from deserializer threadid string from deserializer hostname string from deserializer sessionid string from deserializer dt string # Partition Information # col_name data_type comment dt string Detailed Table Information Table(tableName:impressions, dbName:sampledb, owner:hadoop, createTime:1587610521, lastAccessTime:0, retention:0, sd:StorageDescriptor(cols:[FieldSchema(name:requestbegintime, type:string, comment:null), FieldSchema(name:adid, type:string, comment:null), FieldSchema(name:impressionid, type:string, comment:null), FieldSchema(name:referrer, type:string, comment:null), FieldSchema(name:useragent, type:string, comment:null), FieldSchema(name:usercookie, type:string, comment:null), FieldSchema(name:ip, type:string, comment:null), FieldSchema(name:number, type:string, comment:null), FieldSchema(name:processid, type:string, comment:null), FieldSchema(name:browsercokie, type:string, comment:null), FieldSchema(name:requestendtime, type:string, comment:null), FieldSchema(name:timers, type:struct, comment:null), FieldSchema(name:threadid, type:string, comment:null), FieldSchema(name:hostname, type:string, comment:null), FieldSchema(name:sessionid, type:string, comment:null)], location:s3://us-east-1.elasticmapreduce/samples/hive-ads/tables/impressions, inputFormat:org.apache.hadoop.mapred.TextInputFormat, outputFormat:org.apache.hadoop.hive.ql.io.IgnoreKeyTextOutputFormat, compressed:false, numBuckets:-1, serdeInfo:SerDeInfo(name:null, serializationLib:org.openx.data.jsonserde.JsonSerDe, parameters:{serialization.format=1, paths=requestbegintime, adid, impressionid, referrer, useragent, usercookie, ip}), bucketCols:[], sortCols:[], parameters:{}, skewedInfo:SkewedInfo(skewedColNames:[], skewedColValues:[], skewedColValueLocationMaps:{}), storedAsSubDirectories:false), partitionKeys:[FieldSchema(name:dt, type:string, comment:null)], parameters:{EXTERNAL=TRUE, transient_lastDdlTime=1587610521}, viewOriginalText:null, viewExpandedText:null, tableType:EXTERNAL_TABLE) ``` # DESCRIBE VIEW Mostra a lista de colunas para a visualização do Athena ou do AWS Glue Data Catalog especificada. Útil para examinar os atributos de uma visualização complexa. Para visualizações do Catálogo de Dados, a saída da instrução é controlada pelo controle de acesso do Lake Formation e mostra somente as colunas às quais o chamador tem acesso. ## Resumo ``` DESCRIBE [db_name.]view_name ``` ## Exemplo ``` DESCRIBE orders ``` Consulte também [SHOW COLUMNS](show-columns.md), [SHOW CREATE VIEW](show-create-view.md), [SHOW VIEWS](show-views.md) e [DROP VIEW](drop-view.md). # DROP DATABASE Remove o banco de dados nomeado do catálogo. Se o banco de dados incluir tabelas, você deverá descartá-las antes de executar `DROP DATABASE` ou usar a cláusula `CASCADE`. O uso de `DATABASE` e `SCHEMA` é intercambiável. Eles significam a mesma coisa. ## Resumo ``` DROP {DATABASE | SCHEMA} [IF EXISTS] database_name [RESTRICT | CASCADE] ``` ## Parâmetros **[SE EXISTIR]** Fará o erro ser suprimido se `database_name` não existir. **[RESTRICT\$1CASCADE]** Determina como tabelas dentro de `database_name` são consideradas durante a operação `DROP`. Se você especificar `RESTRICT`, o banco de dados não será ignorado se ele contiver tabelas. Esse é o comportamento padrão. Especificar `CASCADE` faz o banco de dados e todas as tabelas serem ignorados. ## Exemplos ``` DROP DATABASE clickstreams; ``` ``` DROP SCHEMA IF EXISTS clickstreams CASCADE; ``` **nota** Quando você tenta eliminar um banco de dados cujo nome tem caracteres especiais (p. ex., `my-database`), você pode receber uma mensagem de erro. Para resolver esse problema, tente delimitar o nome do banco de dados com caracteres de crase (`). Para obter mais informações sobre nomenclatura de bancos de dados no Athena, consulte [Nomear bancos de dados, tabelas e colunas](tables-databases-columns-names.md). # DROP TABLE Remove a definição da tabela de metadados da tabela nomeada `table_name`. Quando você descarta uma tabela externa, os dados subjacentes permanecem intactos. ## Resumo ``` DROP TABLE [IF EXISTS] table_name ``` ## Parâmetros **[ IF EXISTS ]** Fará o erro ser suprimido se `table_name` não existir. ## Exemplos ``` DROP TABLE fulfilled_orders ``` ``` DROP TABLE IF EXISTS fulfilled_orders ``` Ao usar o editor de consultas do console do Athena para descartar uma tabela que tenha caracteres especiais diferentes de sublinhados (\$1), use acentos graves, como no exemplo a seguir. ``` DROP TABLE `my-athena-database-01.my-athena-table` ``` Ao usar o conector JDBC para soltar uma tabela que tenha caracteres especiais, os caracteres de acento grave não são necessários. ``` DROP TABLE my-athena-database-01.my-athena-table ``` # DROP VIEW Descarta (exclui) uma visualização existente do Athena ou do AWS Glue Data Catalog. A cláusula `IF EXISTS` opcional faz com que o erro seja suprimido se a exibição não existir. Para visualizações do Catálogo de Dados, descarta a visualização somente se a sintaxe da visualização do Athena (dialeto) estiver presente na visualização do Catálogo de Dados. Por exemplo, se um usuário chamar `DROP VIEW` a partir do Athena, a visualização será descartada somente se o dialeto do Athena existir na visualização. Caso contrário, haverá falha na operação. O descarte de visualizações do Catálogo de Dados requer permissões de administrador ou definidor de visualizações do Lake Formation. Para ter mais informações, consulte [Trabalhar com visualizações](views.md) e [Usar visualizações do Catálogo de Dados no Athena](views-glue.md). ## Resumo ``` DROP VIEW [ IF EXISTS ] view_name ``` ## Exemplos ``` DROP VIEW orders_by_date ``` ``` DROP VIEW IF EXISTS orders_by_date ``` Consulte também [CREATE VIEW e da CREATE PROTECTED MULTI DIALECT VIEW](create-view.md), [SHOW COLUMNS](show-columns.md), [SHOW CREATE VIEW](show-create-view.md), [SHOW VIEWS](show-views.md) e [DESCRIBE VIEW](describe-view.md). # MSCK REPAIR TABLE Use o comando `MSCK REPAIR TABLE` para atualizar os metadados no catálogo depois de adicionar partições compatíveis com o Hive. O comando `MSCK REPAIR TABLE` verifica um sistema de arquivos, como o Amazon S3, para procurar se há partições compatíveis com o Hive que foram adicionadas ao sistema de arquivos após a criação da tabela. `MSCK REPAIR TABLE` compara as partições nos metadados da tabela e as partições no S3. Se houver novas partições no local do S3 que você especificou quando criou a tabela, ele as adicionará aos metadados e à tabela do Athena. Quando você adiciona partições físicas, os metadados no catálogo ficam inconsistentes com o layout dos dados no sistema de arquivos, e é necessário adicionar informações sobre as novas partições ao catálogo. Para atualizar os metadados, execute `MSCK REPAIR TABLE` para que você possa consultar os dados nas novas partições do Athena. **nota** `MSCK REPAIR TABLE` somente adiciona partições aos metadados, não as remove. Para remover partições dos metadados depois que elas foram excluídas manualmente do Amazon S3, execute o comando `ALTER TABLE table-name DROP PARTITION`. Para obter mais informações, consulte [ALTER TABLE DROP PARTITION](alter-table-drop-partition.md). ## Considerações e limitações Ao usar `MSCK REPAIR TABLE`, lembre-se dos seguintes pontos: + É possível que demore algum tempo para adicionar todas as partições. Se expirar, essa operação estará em um estado incompleto, quando somente algumas partições são adicionadas ao catálogo. Você deve executar `MSCK REPAIR TABLE` na mesma tabela até que todas as partições sejam adicionadas. Para obter mais informações, consulte [Particionar dados](partitions.md). + Para as partições que não são compatíveis com o Hive, use [ALTER TABLE ADD PARTITION](alter-table-add-partition.md) para carregá-las para poder consultar os dados. + Os locais das partições que serão usados com o Athena devem aplicar o protocolo do `s3` (por exemplo, `s3://amzn-s3-demo-bucket/folder/`). No Athena, os locais que usam outros protocolos (por exemplo, `s3a://bucket/folder/`) resultam em falhas nas consultas `MSCK REPAIR TABLE` quando elas são executadas nas tabelas que os contêm. + Como `MSCK REPAIR TABLE` verifica uma pasta e as subpastas para encontrar um esquema de partição correspondente, mantenha os dados das tabelas separadas em hierarquias de pastas separadas. Por exemplo, suponha que você tenha dados na tabela 1 em `s3://amzn-s3-demo-bucket1` e dados na tabela 2 em `s3://amzn-s3-demo-bucket1/table-2-data`. Se ambas as tabelas forem particionadas por string, `MSCK REPAIR TABLE` adicionará as partições da tabela 2 à tabela 1. Para evitar isso, use estruturas de pastas separadas, como `s3://amzn-s3-demo-bucket1` e `s3://amzn-s3-demo-bucket2`. Observe que esse comportamento é consistente com o Amazon EMR e o Apache Hive. + Devido a um problema conhecido, a `MSCK REPAIR TABLE` falha silenciosamente quando os valores da partição contêm dois pontos (`:`), por exemplo, quando o valor da partição é um carimbo de data/hora. Como solução alternativa, use [ALTER TABLE ADD PARTITION](alter-table-add-partition.md). + `MSCK REPAIR TABLE` X não adiciona nomes de colunas de partição que começam com um sublinhado (\$1). Para contornar essa limitação, utilize [ALTER TABLE ADD PARTITION](alter-table-add-partition.md). ## Resumo ``` MSCK REPAIR TABLE table_name ``` ## Exemplos ``` MSCK REPAIR TABLE orders; ``` ## Solução de problemas Depois que você executar `MSCK REPAIR TABLE`, se o Athena não adicionar as partições à tabela no AWS Glue Data Catalog, verifique o seguinte: + **Acesso do AWS Glue**: certifique-se de que o perfil do AWS Identity and Access Management (IAM) tenha uma política que permita a ação `glue:BatchCreatePartition`. Para obter mais informações, consulte [Permitir glue:BatchCreatePartition na política do IAM](#msck-repair-table-troubleshooting-allow-gluebatchcreatepartition-in-the-policy) adiante neste documento. + **Acesso do Amazon S3**: certifique-se de que o perfil tenha uma política com permissões suficientes para acessar o Amazon S3, incluindo a ação [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DescribeJob.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DescribeJob.html). Para ver um exemplo das ações do Amazon S3 que devem ser permitidas, consulte o exemplo de política de bucket em [Configurar o acesso entre contas do Athena aos buckets do Amazon S3](cross-account-permissions.md). + **Uso de maiúsculas e minúsculas em chaves de objeto do Amazon S3**: verifique se o caminho do Amazon S3 está em letras minúsculas em vez de minúsculas concatenadas (por exemplo, `userid` em vez de `userId`) ou use `ALTER TABLE ADD PARTITION` para especificar os nomes de chaves de objeto. Para obter mais informações, consulte [Alterar ou redefinir o caminho do Amazon S3](#msck-repair-table-troubleshooting-change-or-redefine-the-amazon-s3-path) adiante neste documento. + **Tempo limite de consulta esgotado**: é melhor usar `MSCK REPAIR TABLE` para criar uma tabela pela primeira vez ou quando há incerteza sobre a paridade entre os dados e os metadados da partição. Se você usa `MSCK REPAIR TABLE` para adicionar novas partições com frequência (por exemplo, diariamente) e sempre enfrenta problemas de tempo limite de consulta esgotado, considere usar [ALTER TABLE ADD PARTITION](alter-table-add-partition.md). + **Partições ausentes do sistema de arquivos**: se você excluir manualmente uma partição do Amazon S3 e executar `MSCK REPAIR TABLE`, poderá receber a mensagem de erro: Partições ausentes do sistema de arquivos. Isso ocorre porque `MSCK REPAIR TABLE` não remove partições obsoletas dos metadados da tabela. Em vez disso, execute [ALTER TABLE DROP PARTITION](alter-table-drop-partition.md) para remover as partições excluídas dos metadados da tabela. Do mesmo modo, veja que [SHOW PARTITIONS](show-partitions.md) lista apenas as partições nos metadados, e não as partições no sistema de arquivos. + **"Erro “NullPointerException name is null” (O nome de NullPointerException é nulo** Se você usar a operação de API do AWS Glue [CreateTable](https://docs.aws.amazon.com/glue/latest/webapi/API_CreateTable.html) ou o modelo [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-glue-table.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-glue-table.html) do CloudFormation para criar uma tabela para uso no Athena sem especificar a propriedade `TableType` e, depois, executar uma consulta DDL, como `SHOW CREATE TABLE` ou `MSCK REPAIR TABLE`, poderá receber a mensagem de erro FALHA: o nome de NullPointerException é nulo. Para resolver o erro, especifique um valor para o atributo [TableInput](https://docs.aws.amazon.com/glue/latest/webapi/API_TableInput.html) `TableType` como parte da chamada de API `CreateTable` do AWS Glue ou do [modelo do CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-glue-table-tableinput.html). Os valores possíveis para `TableType` são `EXTERNAL_TABLE` ou `VIRTUAL_VIEW`. Esse requisito é aplicado somente quando você cria uma tabela usando a operação de API do AWS Glue `CreateTable` ou o modelo do `AWS::Glue::Table`. Se você criar uma tabela do Athena usando uma instrução DDL ou um crawler do AWS Glue, a propriedade `TableType` será definida automaticamente para você. As seções a seguir apresentam mais detalhes. ### Permitir glue:BatchCreatePartition na política do IAM Analise as políticas do IAM vinculadas ao perfil que você usa para executar `MSCK REPAIR TABLE`. Quando você [usa o AWS Glue Data Catalog com o Athena](data-sources-glue.md), a política do IAM deve permitir a ação `glue:BatchCreatePartition`. Para ver um exemplo de uma política do IAM que permite a ação `glue:BatchCreatePartition`, consulte [AWSPolítica gerenciada pela : AmazonAthenaFullAccess](security-iam-awsmanpol.md#amazonathenafullaccess-managed-policy). ### Alterar ou redefinir o caminho do Amazon S3 Se uma ou mais chaves de objeto no caminho do Amazon S3 estiverem em letras minúsculas concatenadas em vez de minúsculas, talvez `MSCK REPAIR TABLE` não adicione as partições ao AWS Glue Data Catalog. Por exemplo, se o caminho do Amazon S3 incluir o nome da chave do objeto `userId`, talvez as seguintes partições não sejam adicionadas ao AWS Glue Data Catalog: ``` s3://amzn-s3-demo-bucket/path/userId=1/ s3://amzn-s3-demo-bucket/path/userId=2/ s3://amzn-s3-demo-bucket/path/userId=3/ ``` Para resolver esse problema, execute um dos seguintes procedimentos: + Use letras minúsculas em vez de minúsculas concatenadas ao criar chaves de objeto do Amazon S3: ``` s3://amzn-s3-demo-bucket/path/userid=1/ s3://amzn-s3-demo-bucket/path/userid=2/ s3://amzn-s3-demo-bucket/path/userid=3/ ``` + Use [ALTER TABLE ADD PARTITION](alter-table-add-partition.md) para redefinir o local, como no seguinte exemplo: ``` ALTER TABLE table_name ADD [IF NOT EXISTS] PARTITION (userId=1) LOCATION 's3://amzn-s3-demo-bucket/path/userId=1/' PARTITION (userId=2) LOCATION 's3://amzn-s3-demo-bucket/path/userId=2/' PARTITION (userId=3) LOCATION 's3://amzn-s3-demo-bucket/path/userId=3/' ``` Embora os nomes de chave de objeto do Amazon S3 possam usar letras maiúsculas, os nomes de bucket do Amazon S3 devem estar sempre em letras minúsculas. Para obter mais informações, consulte [Diretrizes de nomeação de chave de objeto](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-guidelines) e [Regras de nomeação de bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) no *Guia do usuário do Amazon S3*. # SHOW COLUMNS Mostra somente os nomes das colunas para uma tabela especificada única, uma visualização do Athena ou uma visualização do Catálogo de Dados. Para obter informações mais detalhadas sobre visualizações do Athena, consulte o AWS Glue Data Catalog. Para obter informações e exemplos, consulte as seguintes seções do tópico [Consultar o AWS Glue Data Catalog](querying-glue-catalog.md): + Para visualizar os metadados de coluna, como tipo de dados, consulte [Listar ou pesquisar colunas de uma tabela ou visualização especificada](querying-glue-catalog-listing-columns.md). + Para visualizar todas as colunas de todas as tabelas em um banco de dados específico no `AwsDataCatalog`, consulte [Listar ou pesquisar colunas de uma tabela ou visualização especificada](querying-glue-catalog-listing-columns.md). + Para visualizar todas as colunas de todas as tabelas em todos os bancos de dados no `AwsDataCatalog`, consulte [Listar todas as colunas de todas as tabelas](querying-glue-catalog-listing-all-columns-for-all-tables.md). + Para visualizar as colunas que tabelas específicas têm em comum em um banco de dados, consulte [Listar colunas que tabelas específicas têm em comum](querying-glue-catalog-listing-columns-in-common.md). Para visualizações do Catálogo de Dados, a saída da instrução é controlada pelo controle de acesso do Lake Formation e mostra somente as colunas às quais o chamador tem acesso. ## Resumo ``` SHOW COLUMNS {FROM|IN} database_name.table_or_view_name ``` ``` SHOW COLUMNS {FROM|IN} table_or_view_name [{FROM|IN} database_name] ``` É possível usar as palavras-chave `FROM` e `IN` de forma intercambiável. Se *table\$1or\$1view\$1name* ou *database\$1name* tiver caracteres especiais como hifens, coloque-os entre acentos graves (por exemplo, ``my-database`.`my-table``). Não coloque *table\$1or\$1view\$1name* ou *database\$1name* entre aspas simples ou duplas. Atualmente, o uso de `LIKE` e das expressões de correspondência de padrões não é permitido. ## Exemplos Os exemplos equivalentes a seguir mostram as colunas da tabela `orders` no banco de dados `customers`. Os dois primeiros exemplos consideram o banco de dados `customers` como o atual. ``` SHOW COLUMNS FROM orders ``` ``` SHOW COLUMNS IN orders ``` ``` SHOW COLUMNS FROM customers.orders ``` ``` SHOW COLUMNS IN customers.orders ``` ``` SHOW COLUMNS FROM orders FROM customers ``` ``` SHOW COLUMNS IN orders IN customers ``` # SHOW CREATE TABLE Analisa uma tabela existente chamada `table_name` para gerar a consulta que a criou. ## Resumo ``` SHOW CREATE TABLE [db_name.]table_name ``` ## Parâmetros **TABLE [db\$1name.]table\$1name** O parâmetro `db_name` é opcional. Se omitido, o contexto assumirá como padrão o banco de dados atual. O nome da tabela é obrigatório. ## Exemplos ``` SHOW CREATE TABLE orderclickstoday; ``` ``` SHOW CREATE TABLE `salesdata.orderclickstoday`; ``` ## Solução de problemas Se você usar a operação de API do AWS Glue [CreateTable](https://docs.aws.amazon.com/glue/latest/webapi/API_CreateTable.html) ou o modelo [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-glue-table.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-glue-table.html) do CloudFormation para criar uma tabela para uso no Athena sem especificar a propriedade `TableType` e, depois, executar uma consulta DDL, como `SHOW CREATE TABLE` ou `MSCK REPAIR TABLE`, poderá receber a mensagem de erro FALHA: o nome de NullPointerException é nulo. Para resolver o erro, especifique um valor para o atributo [TableInput](https://docs.aws.amazon.com/glue/latest/webapi/API_TableInput.html) `TableType` como parte da chamada de API `CreateTable` do AWS Glue ou do [modelo do CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-glue-table-tableinput.html). Os valores possíveis para `TableType` são `EXTERNAL_TABLE` ou `VIRTUAL_VIEW`. Esse requisito é aplicado somente quando você cria uma tabela usando a operação de API do AWS Glue `CreateTable` ou o modelo do `AWS::Glue::Table`. Se você criar uma tabela do Athena usando uma instrução DDL ou um crawler do AWS Glue, a propriedade `TableType` será definida automaticamente para você. # SHOW CREATE VIEW Mostra a instrução SQL que criou a visualização específica do Athena ou do Catálogo de Dados. O SQL retornado mostra a sintaxe de criação de visualização usada no Athena. A chamada a `SHOW CREATE VIEW` em visualizações do Catálogo de Dados requer permissões de administrador ou definidor de visualizações do Lake Formation. ## Resumo ``` SHOW CREATE VIEW view_name ``` ## Exemplos ``` SHOW CREATE VIEW orders_by_date ``` Consulte também [CREATE VIEW e da CREATE PROTECTED MULTI DIALECT VIEW](create-view.md) e [DROP VIEW](drop-view.md). # SHOW DATABASES Lista todos os bancos de dados definidos na metastore. Você pode usar `DATABASES` ou `SCHEMAS`. Eles significam a mesma coisa. O equivalente programático de `SHOW DATABASES` é a ação da API [ListDatabases](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListDatabases.html) do Athena. O método equivalente em AWS SDK para Python (Boto3) é [list\$1databases](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/athena/client/list_databases.html). ## Resumo ``` SHOW {DATABASES | SCHEMAS} [LIKE 'regular_expression'] ``` ## Parâmetros **[LIKE '*regular\$1expression*']** Filtra a lista de bancos de dados aos correspondentes à `regular_expression` especificada por você. Para correspondência de caracteres curinga, você pode usar a combinação `.*`, que associa qualquer caractere zero a multiplicações ilimitadas. ## Exemplos ``` SHOW SCHEMAS; ``` ``` SHOW DATABASES LIKE '.*analytics'; ``` # SHOW PARTITIONS Lista todas as partições em uma tabela do Athena em uma ordem não classificada. ## Resumo ``` SHOW PARTITIONS table_name ``` + Para exibir as partições em uma tabela e listá-las em uma ordem específica, consulte a seção [Listar partições de uma tabela específica](querying-glue-catalog-listing-partitions.md) na página [Consultar o AWS Glue Data Catalog](querying-glue-catalog.md). + Para visualizar o conteúdo de uma partição, consulte a seção [Consultar os dados](partitions.md#query-the-data) na página [Particionar dados](partitions.md). + `SHOW PARTITIONS` não lista as partições que foram projetadas pelo Athena, mas que não estão registradas no catálogo do AWS Glue. Para obter informações sobre a projeção de partições, consulte [Usar projeção de partições com o Amazon Athena](partition-projection.md). + `SHOW PARTITIONS` lista as partições nos metadados, não as partições no sistema de arquivos real. Para atualizar os metadados depois que você excluir manualmente as partições do Amazon S3, execute [ALTER TABLE DROP PARTITION](alter-table-drop-partition.md). ## Exemplos A consulta de exemplo a seguir mostra as partições da tabela `flight_delays_csv`, que inclui os dados da tabela de voos do Departamento de Transporte dos EUA. Para obter mais informações sobre a tabelas `flight_delays_csv` de exemplo, consulte [Lazy Simple SerDe para arquivos CSV, TSV e com delimitação personalizada](lazy-simple-serde.md). A tabela está particionada por ano. ``` SHOW PARTITIONS flight_delays_csv ``` **Resultados** ``` year=2007 year=2015 year=1999 year=1993 year=1991 year=2003 year=1996 year=2014 year=2004 year=2011 ... ``` A consulta de exemplo a seguir mostra as partições da tabela `impressions`, que inclui amostra de dados de navegação na Web. Para obter mais informações sobre a tabelas `impressions` de exemplo, consulte [Particionar dados](partitions.md). A tabela está particionada pela coluna `dt` (data e hora). ``` SHOW PARTITIONS impressions ``` **Resultados** ``` dt=2009-04-12-16-00 dt=2009-04-13-18-15 dt=2009-04-14-00-20 dt=2009-04-12-13-00 dt=2009-04-13-02-15 dt=2009-04-14-12-05 dt=2009-04-14-06-15 dt=2009-04-12-21-15 dt=2009-04-13-22-15 ... ``` ### Listar partições em ordem de classificação Para ordenar as partições na lista de resultados, use a sintaxe `SELECT` a seguir, em vez de `SHOW PARTITIONS`. ``` SELECT * FROM database_name."table_name$partitions" ORDER BY column_name ``` A consulta a seguir mostra a lista das partições do exemplo de `flight_delays_csv`, mas agora classificada. ``` SELECT * FROM "flight_delays_csv$partitions" ORDER BY year ``` **Resultados** ``` year 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 ... ``` Para obter mais informações, consulte a seção [Listar partições de uma tabela específica](querying-glue-catalog-listing-partitions.md) na página [Consultar o AWS Glue Data Catalog](querying-glue-catalog.md). # SHOW TABLES Lista todas as tabelas base e exibe em um banco de dados. **nota** O parâmetro [StatementType](https://docs.aws.amazon.com/athena/latest/APIReference/API_QueryExecution.html#athena-Type-QueryExecution-StatementType) para `SHOW TABLES` na operação da API [GetQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetQueryExecution.html) é categorizado como `UTILITY`, e não `DDL`. ## Resumo ``` SHOW TABLES [IN database_name] ['regular_expression'] ``` ## Parâmetros **[IN database\$1name]** Especifica o `database_name` de quais tabelas serão listadas. Se omitido, o banco de dados do contexto atual é assumido. `SHOW TABLES` poderá falhar se `database_name` usar um [caractere sem suporte](tables-databases-columns-names.md), como o hífen. Como solução alternativa, tente delimitar o nome do banco de dados com acentos graves. **['regular\$1expression']** Filtra a lista de tabelas às correspondentes ao `regular_expression` especificado por você. Para indicar qualquer caractere nas tabelas `AWSDataCatalog`, você pode usar a expressão curinga `*` ou `.*`. Para bancos de dados do Apache Hive, use a expressão curinga `.*`. Para indicar uma opção entre caracteres, use o caractere `|`. ## Exemplos **Example – mostrar todas as tabelas no banco de dados `sampledb`** ``` SHOW TABLES IN sampledb ``` `Results` ``` alb_logs cloudfront_logs elb_logs flights_2016 flights_parquet view_2016_flights_dfw ``` **Example – mostrar os nomes de todas as tabelas em `sampledb` que incluem a palavra “flights”** ``` SHOW TABLES IN sampledb '*flights*' ``` `Results` ``` flights_2016 flights_parquet view_2016_flights_dfw ``` **Example – mostrar os nomes de todas as tabelas em `sampledb` que terminam com a palavra “logs”** ``` SHOW TABLES IN sampledb '*logs' ``` `Results` ``` alb_logs cloudfront_logs elb_logs ``` # SHOW TBLPROPERTIES Lista as propriedades da tabela nomeada. ## Resumo ``` SHOW TBLPROPERTIES table_name [('property_name')] ``` ## Parâmetros **[('property\$1name')]** Se incluído, somente o valor da propriedade chamada `property_name` será listado. ## Exemplos ``` SHOW TBLPROPERTIES orders; ``` ``` SHOW TBLPROPERTIES orders('comment'); ``` # SHOW VIEWS Lista as visualizações do Athena ou do Catálogo de Dados em uma lista de valores do tipo `STRING`. Cada valor na lista é o nome de uma visualização no banco de dados especificado ou no banco de dados atual se você omitir o nome do banco de dados. Use a cláusula `LIKE` opcional com uma expressão regular para restringir a lista de nomes de exibições. Para visualizações do Catálogo de Dados, lista somente as visualizações que usam a sintaxe do Athena SQL. Outras visualizações do Catálogo de Dados são filtradas. ## Resumo ``` SHOW VIEWS [IN database_name] [LIKE 'regular_expression'] ``` ### Parâmetros **[IN database\$1name]** Especifica o `database_name` do qual as exibições serão listadas. Se omitido, o banco de dados do contexto atual é assumido. **[LIKE 'regular\$1expression']** Filtra a lista de exibições às correspondentes ao `regular_expression` especificado por você. Somente o caractere curinga `*`, o que indica qualquer caractere, ou `|`, o que indica uma escolha entre caracteres, podem ser usados. ## Exemplos ``` SHOW VIEWS ``` ``` SHOW VIEWS IN marketing_analytics LIKE 'orders*' ``` Consulte também [SHOW COLUMNS](show-columns.md), [SHOW CREATE VIEW](show-create-view.md), [DESCRIBE VIEW](describe-view.md) e [DROP VIEW](drop-view.md). # Considerações e limitações das consultas SQL no Amazon Athena Ao executar consultas no Athena, tenha em mente as considerações e limitações a seguir. + **Procedimentos armazenados**: não há suporte para procedimentos armazenados. + **Número máximo de partições**: o número máximo de partições que você pode criar com instruções `CREATE TABLE AS SELECT` (CTAS) é 100. Para obter informações, consulte [CREATE TABLE AS](create-table-as.md). Para obter uma solução alternativa, consulte [Usar CTAS e INSERT INTO para resolver o limite de 100 partições](ctas-insert-into.md). + **Instruções não permitidas** — As seguintes instruções não são permitidas. Para ver uma lista completa de instruções de DDL não permitidas no Athena, consulte [DDL incompatível](unsupported-ddl.md). + `CREATE TABLE LIKE`Não há suporte ao . + `DESCRIBE INPUT` e `DESCRIBE OUTPUT` não são aceitos. + A instrução `MERGE` é compatível somente com formatos de tabela transacional. Para obter mais informações, consulte [MERGE INTO](merge-into-statement.md). + `UPDATE`As instruções não são compatíveis. + `DELETE FROM`Não há suporte ao . + **Conectores Trino e Presto **: não há compatibilidade com conectores [Trino](https://trino.io/docs/current/connector.html) nem [Presto](https://prestodb.io/docs/current/connector.html). Use a consulta federada do Amazon Athena para conectar origens de dados. Para obter mais informações, consulte [Usar a consulta federada do Amazon Athena](federated-queries.md). + **Tempo limite esgotado em tabelas com muitas partições**: o Athena pode esgotar o tempo limite ao consultar uma tabela com milhares de partições. Isso pode acontecer quando a tabela tem muitas partições que não são do tipo `string`. Quando você usa o tipo `string`, o Athena remove as partições no nível do metastore. No entanto, quando você usa outros tipos de dados, o Athena remove as partições do servidor. Quanto mais partições você tiver, mais tempo esse processo levará e maior será a probabilidade de suas consultas atingirem o tempo limite. Para resolver esse problema, defina o tipo de partição como `string` para que o Athena remova as partições no nível do metastore. Isso reduz a sobrecarga e evita que as consultas atinjam o tempo limite. + Compatibilidade com o **Amazon Glacier**: para obter informações sobre como consultar objetos restaurados do Amazon Glacier, consulte [Consultar os objetos restaurados do Amazon Glacier](querying-glacier.md). + **Arquivos tratados como ocultos**: o Athena trata os arquivos de origem que começam com sublinhado (`_`) ou ponto (`.`) como ocultos. Para contornar essa limitação, renomeie os arquivos. + **Limitação de tamanho de linha ou coluna**: o tamanho de uma única linha ou de suas colunas não pode exceder 32 MB. Esse limite pode ser excedido quando, por exemplo, uma linha contiver uma única coluna de 35 MB. Esse é um limite fixo do serviço e não pode ser alterado. + **Tamanho máximo da linha em um arquivo de texto**: o tamanho de uma única linha em um arquivo de texto tem um limite superior de 200 MB. Exceder esse limite pode gerar a mensagem de erro TextLineLengthLimitExceededException: Too many bytes before newline. Para contornar essa limitação, garanta que você não tenha uma única linha em um arquivo de texto com mais de 200 MB. + **Cláusula LIMIT máxima**: o número máximo de linhas que podem ser especificadas para a cláusula `LIMIT` é 9223372036854775807. Ao usar `ORDER BY`, o número máximo de linhas permitido para a cláusula LIMIT é 2.147.483.647. Exceder esse limite resultará na mensagem de erro NOT\$1SUPPORTED: ORDER BY LIMIT > 2147483647 is not supported [Não há suporte para ORDER BY LIMIT > 2147483647]. + **information\$1schema**: as consultas de `information_schema` apresentam melhor desempenho se você tiver uma quantidade pequena a moderada de metadados do AWS Glue. Pode haver erros se você tiver uma grande quantidade de metadados. Para obter informações sobre como consultar o banco de dados `information_schema` para metadados do AWS Glue, consulte [Consultar o AWS Glue Data Catalog](querying-glue-catalog.md). + **Inicializações de matriz**: devido a uma limitação do Java, não é possível inicializar no Athena uma matriz que tenha mais de 254 argumentos. + **Colunas ocultas de metadados**: as colunas de metadados ocultas do Hive ou do Iceberg `$bucket`, `$file_modified_time`, `$file_size` e `$partition` não são compatíveis para visualizações. Para obter informações sobre como usar a coluna `$path` de metadados no Athena, consulte [Obter os locais de arquivos dos dados de origem no Amazon S3](select.md#select-path). Para obter informações sobre o tamanho máximo da cadeia de caracteres de consulta, cotas para tempos limite de consulta e cotas para o número ativo de consultas DML, acesse [Service Quotas](service-limits.md).