UNLOAD - Amazon Athena
Considerações e limitaçõesSintaxeExemplosRecursos adicionais

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 ter mais informações, consulte Identificar arquivos de saída de consultas.

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

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

  • Cotas de serviço: o UNLOAD usa cotas de consultas em DML. Para obter informações sobre cotas, consulte Service Quotas.

  • 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 ter mais informações, consulte Especificar um local para resultados de consultas com uso do console do Athena.

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

format = 'file_format'

Obrigatório. Especifica o formato de arquivo da saída. Os valores possíveis para file_format são ORC, PARQUET, AVRO, JSON ouTEXTFILE.

compression = 'compression_format'

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.

nota

Essa opção não se aplica ao formato AVRO. O Athena usa gzip para os formatos JSON e TEXTFILE.

compression_level = compression_level

Opcional. O nível de compactação a ser usado para compactação ZSTD. Essa propriedade se aplica apenas à compactação ZSTD. Para ter mais informações, consulte Usar níveis de compactação ZSTD.

field_delimiter = '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_by = ARRAY[ col_name[,...] ]

Opcional. Uma lista matriz de colunas pela qual a saída é particionada.

nota

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