CREATE TABLE - Amazon Athena
ResumoParâmetrosExemplos

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. 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.

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://DOC-EXAMPLE-BUCKET/[folder]/']
 [TBLPROPERTIES ( ['has_encrypted_data'='true | false',] ['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, 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_name.]table_name

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.

[ ( col_name data_type [COMMENT col_comment] [, ...] ) ]

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`.

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+308d, 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+38, 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).

  • 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 (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 (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 ter mais informações, consulte OpenCSVSerDe para processar CSV.

  • timestamp: instante de data e hora em um formato compatível com java.sql.Timestamp 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 ter mais informações, consulte OpenCSVSerDe para processar CSV.

  • array < data_type >

  • map < primitive_type, data_type >

  • struct < col_name : data_type [comment col_comment] [, ...] >

[COMMENT table_comment]

Cria a propriedade da tabela comment e a preenche com o table_comment especificado por você.

[PARTITIONED BY (col_name data_type [ COMMENT col_comment ], ... ) ]

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.

nota

Depois de criar uma tabela com partições, execute uma consulta que consista na cláusula MSCK REPAIR TABLE 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 a fim de carregar as partições para que você consiga consultar os dados.

[CLUSTERED BY (col_name, col_name, ...) INTO num_buckets 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_format]

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_name' [WITH SERDEPROPERTIES ("property_name" = "property_value", "property_name" = "property_value" [, ...] )]

    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_format_classname OUTPUTFORMAT output_format_classname

[LOCATION 's3://DOC-EXAMPLE-BUCKET/[pasta]/']

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 Local da tabela no Amazon S3. Para obter informações sobre formatos de dados e permissões, consulte Requisitos para tabelas no Athena e dados no Amazon S3.

Use uma barra à direita para a pasta ou o bucket. Não use nomes de arquivo ou caracteres glob.

Use:

s3://DOC-EXAMPLE-BUCKET/

s3://DOC-EXAMPLE-BUCKET/folder/

s3://DOC-EXAMPLE-BUCKET/folder/anotherfolder/

Não use:

s3://DOC-EXAMPLE-BUCKET

s3://DOC-EXAMPLE-BUCKET/*

s3://DOC-EXAMPLE-BUCKET/mydatafile.dat

[TBLPROPERTIES ( ['has_encrypted_data'='true | false',] ['classification'='classification_value',] property_name=property_value [, ...] ) ]

Especifica pares de chave/valor de metadados personalizados para a definição da tabela, além das propriedades da tabela predefinidas, como "comment".

has_encrypted_data: 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. 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 ter mais informações, consulte Criptografia inativa.

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 Criar trabalhos de ETL e Criar trabalhos no AWS Glue no Guia do desenvolvedor do AWS Glue.

compression_level: a propriedade compression_level especifica o nível de compactaçã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 compressão ZSTD no Athena.

Para obter mais informações sobre outras propriedades de tabelas, consulte ALTER TABLE SET TBLPROPERTIES.

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://DOC-EXAMPLE-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 ('\t').

  • 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.