UNLOAD - Amazon Athena
Consideraciones y limitacionesSintaxisEjemplosRecursos adicionales de

UNLOAD

Escribe los resultados de la consulta desde una instrucción SELECT al formato de datos especificado. Los formatos admitidos para UNLOAD incluyen Apache Parquet, ORC, Apache Avro y JSON. CSV es el único formato de salida compatible con el comando SELECT de Athena; no obstante, pero puede usar el comando UNLOAD, que admite una variedad de formatos de salida, para incluir la consulta SELECT y reescribir su salida en uno de los formatos compatibles con UNLOAD.

Si bien puede utilizar la instrucción CTAS para generar datos en formatos distintos a CSV, esas instrucciones también requieren la creación de una tabla en Athena. La instrucción UNLOAD es útil cuando se desea generar los resultados de una consulta SELECT en un formato que no sea CSV, pero no se requiere la tabla asociada. Por ejemplo, una aplicación descendente puede requerir que los resultados de una consulta SELECT estén en formato JSON, y Parquet u ORC podrían proporcionar una ventaja de rendimiento sobre CSV si tiene la intención de utilizar los resultados de la consulta SELECT para un análisis adicional.

Consideraciones y limitaciones

Cuando utiliza la instrucción UNLOAD en Athena, tenga en cuenta los siguientes puntos:

  • Sin orden global de archivos: los resultados de UNLOAD se escriben en varios archivos en paralelo. Si la consulta SELECT en la instrucción UNLOAD especifica un orden de clasificación, el contenido de cada archivo está en orden de clasificación, pero los archivos no están ordenados entre sí.

  • Datos huérfanos no eliminados: en caso de error, Athena no intenta eliminar datos huérfanos. Este comportamiento es el mismo que en instrucciones CTAS y INSERT INTO.

  • Particiones máximas: el número máximo de particiones que se pueden utilizar con UNLOAD es 100.

  • Archivos de manifiesto y metadatos: Athena genera un archivo de metadatos y un archivo de manifiesto de datos para cada consulta UNLOAD. El manifiesto realiza un seguimiento de los archivos que escribió la consulta. Ambos archivos se guardan en la ubicación de resultados de consulta de Athena en Amazon S3. Para obtener más información, consulte Identificación de archivos de salida de consultas.

  • Cifrado: Los archivos de salida UNLOAD se cifran de acuerdo con la configuración de cifrado utilizada para Amazon S3. Para configurar la configuración de cifrado para cifrar el resultado UNLOAD, puede utilizar la API EncryptionConfiguration.

  • Instrucciones preparadas: UNLOAD se puede utilizar con instrucciones preparadas. Para obtener información acerca de las instrucciones preparadas en Athena, consulte Uso de consultas parametrizadas.

  • Cuotas de servicio: UNLOAD utiliza cuotas de consulta DML. Para obtener información sobre las cuotas, consulte Service Quotas.

  • Propietario esperado del bucket: la configuración del propietario esperado del bucket no se aplica a la ubicación de Amazon S3 de destino especificada en la consulta UNLOAD. La configuración del propietario esperado del bucket se aplica solo a la ubicación de salida de Amazon S3 especificada para los resultados de las consultas de Athena. Para obtener más información, consulte Especificación de una ubicación de resultados de consulta mediante la consola de Athena.

Sintaxis

La instrucción UNLOAD utiliza la siguiente sintaxis.

UNLOAD (SELECT col_name[, ...] FROM old_table) 
TO 's3://DOC-EXAMPLE-BUCKET/my_folder/' 
WITH ( property_name = 'expression' [, ...] )

Excepto cuando se escribe en particiones, el destino de TO debe especificar una ubicación en Amazon S3 que no tenga datos. Antes de que la consulta UNLOAD escriba en la ubicación especificada, verifica que la ubicación del bucket está vacía. Como UNLOAD no escribe datos en la ubicación especificada si la ubicación ya tiene datos en ella, UNLOAD no sobrescribe los datos existentes. Para reutilizar una ubicación de bucket como destino para UNLOAD, elimine los datos de la ubicación del bucket y, a continuación, vuelva a ejecutar la consulta.

Tenga en cuenta que cuando UNLOAD escribe en particiones, este comportamiento es diferente. Si ejecuta la misma consulta UNLOAD varias veces con la misma instrucción SELECT, la misma ubicación TO y las mismas particiones, cada consulta UNLOAD descargará los datos en Amazon S3 en la ubicación y las particiones especificadas.

Parámetros

Los valores posibles para property_name son los siguientes.

format = 'file_format'

Obligatorio. Especifica el formato de archivo de la salida. Los valores posibles para file_format son ORC, PARQUET, AVRO, JSON o TEXTFILE.

compression = 'compression_format'

Opcional. Esta opción es específica de los formatos ORC y Parquet. Para ORC, el valor predeterminado es zlib, y para Parquet, el valor predeterminado es gzip. Para obtener información sobre los formatos de compresión compatibles, consulte Compatibilidad con la compresión de Athena.

nota

Esta opción no se aplica al formato AVRO. Athena utiliza gzip para los formatos JSON y TEXTFILE.

compression_level = compression_level

Opcional. El nivel de compresión que se debe utilizar para la compresión ZSTD. Esta propiedad solo se aplica a la compresión ZSTD. Para obtener más información, consulte Uso de los niveles de compresión ZSTD en Athena.

field_delimiter = 'delimiter'

Opcional. Especifica un delimitador de campo de un solo carácter para archivos con formato CSV, TSV y otros formatos de texto. En el ejemplo siguiente se especifica un delimitador de coma.

WITH (field_delimiter = ',')

Actualmente, no se admiten delimitadores de campos de caracteres múltiples. Si no especifica un delimitador de campo, se utiliza el carácter octal \001 (^A).

partitioned_by = ARRAY[ col_name[,...] ]

Opcional. Una matriz de columnas por las que se particiona la salida.

nota

Asegúrese de que en su instrucción SELECT, los nombres de las columnas particionadas aparezcan en último lugar en la lista de columnas.

Ejemplos

En el siguiente ejemplo se escribe el resultado de una consulta SELECT en la ubicación s3://DOC-EXAMPLE-BUCKET/unload_test_1/ de Amazon S3 utilizando el formato JSON.

UNLOAD (SELECT * FROM old_table) 
TO 's3://DOC-EXAMPLE-BUCKET/unload_test_1/' 
WITH (format = 'JSON')

En el siguiente ejemplo se escribe el resultado de una consulta SELECT en formato Parquet mediante compresión Snappy.

UNLOAD (SELECT * FROM old_table) 
TO 's3://DOC-EXAMPLE-BUCKET/' 
WITH (format = 'PARQUET',compression = 'SNAPPY')

En el siguiente ejemplo se escriben cuatro columnas en formato de texto, con la salida particionada por la última columna.

UNLOAD (SELECT name1, address1, comment1, key1 FROM table1) 
TO 's3://DOC-EXAMPLE-BUCKET/ partitioned/' 
WITH (format = 'TEXTFILE', partitioned_by = ARRAY['key1'])

En el siguiente ejemplo se descargan los resultados de la consulta en la ubicación especificada mediante el formato de archivo Parquet, compresión ZSTD y el nivel 4 de compresión ZSTD.

UNLOAD (SELECT * FROM old_table) 
TO 's3://DOC-EXAMPLE-BUCKET/' 
WITH (format = 'PARQUET', compression = 'ZSTD', compression_level = 4)

Recursos adicionales de