UNLOAD - Amazon Redshift

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

UNLOAD

Descarga el resultado de una consulta en uno o varios archivos de texto o archivos de Apache Parquet en Amazon S3, utilizando el cifrado de servidor de Amazon S3 (SSE-S3). También puede especificar cifrado de servidor con una clave de AWS Key Management Service (SSE-KMS) o cifrado de cliente con una clave administrada por el cliente (CSE-CMK).

Puede administrar el tamaño de los archivos en Amazon S3 y, por extensión, la cantidad de archivos al establecer el parámetro MAXFILESIZE.

Puede descargar el resultado de una consulta de Amazon Redshift en su lago de datos de Amazon S3 en Apache Parquet, un formato de almacenamiento en columnas abierto y eficiente para análisis. El formato de Parquet es hasta 2 veces más rápido de descargar y consumes hasta 6 veces menos almacenamiento en Amazon S3, en comparación con los formatos de texto. Esto le permite guardar transformación y enriquecimiento de datos que haya realizado en Amazon S3 dentro de un lago de datos de Amazon S3 en un formato abierto. A continuación, puede analizar sus datos con Redshift Spectrum y otros servicios de AWS como, por ejemplo, Amazon Athena, Amazon EMR y SageMaker.

Syntax

UNLOAD ('select-statement') TO 's3://object-path/name-prefix' authorization [ option [ ... ] ] where option is { [ FORMAT [ AS ] ] CSV | PARQUET | PARTITION BY ( column_name [, ... ] ) [ INCLUDE ] | MANIFEST [ VERBOSE ] | HEADER | DELIMITER [ AS ] 'delimiter-char' | FIXEDWIDTH [ AS ] 'fixedwidth-spec' | ENCRYPTED [ AUTO ] | BZIP2 | GZIP | ZSTD | ADDQUOTES | NULL [ AS ] 'null-string' | ESCAPE | ALLOWOVERWRITE | PARALLEL [ { ON | TRUE } | { OFF | FALSE } ] | MAXFILESIZE [AS] max-size [ MB | GB ] | REGION [AS] 'aws-region' }

Parameters

('select-statement [instrucción-select]')

Una consulta SELECT. Se descargan los resultados de la consulta. En la mayoría de casos, es útil descargar datos en un orden al especificar una cláusula ORDER BY en la consulta. Este enfoque permite ahorrar el tiempo que se requiere para ordenar los datos cuando se vuelven a cargar.

La consulta debe escribirse entre comillas simples, como se muestra a continuación:

('select * from venue order by venueid')
nota

Si la consulta contiene comillas (por ejemplo, para entrecomillar valores literales), coloque el literal entre dos conjuntos de comillas simples —también debe entrecomillar la consulta entre comillas simples:

('select * from venue where venuestate=''NV''')
TO 's3://object-path/name-prefix (ruta-objeto/prefijo-nombre)'

Ruta completa, incluido el nombre del bucket, de la ubicación de Amazon S3 donde Amazon Redshift escribe los objetos del archivo de salida, incluido el archivo de manifiesto si se ha especificado MANIFEST. Los nombres del objeto tienen el prefijo name-prefix (prefijo-nombre). Si utiliza PARTITION BY, se añade automáticamente una barra diagonal (/) al final del valor nombre-prefijo, si es necesario. Para mayor seguridad, UNLOAD se conecta a Amazon S3 con una conexión HTTPS. Por defecto, UNLOAD escribe uno o más archivos por sector. UNLOAD añade un número de sector y un número de parte al prefijo del nombre especificado, como se muestra a continuación:

<object-path>/<name-prefix><slice-number>_part_<part-number>.

Si se especifica MANIFEST, el archivo de manifiesto se escribe de la siguiente manera:

<object_path>/<name_prefix>manifest.

UNLOAD crea automáticamente archivos cifrados a través del cifrado de servidor (SSE) de Amazon S3, incluido el archivo de manifiesto si se utiliza MANIFEST. El comando COPY lee automáticamente los archivos cifrados del servidor durante la operación de carga. Puede descargar de manera transparente los archivos cifrados del servidor desde el bucket a través de la API o la consola de administración de Amazon S3. Para obtener más información, consulte Protección de los datos con el cifrado del lado del servidor.

Para usar el cifrado del cliente de Amazon S3, especifique la opción ENCRYPTED.

importante

REGION es obligatorio cuando el bucket de Amazon S3 no está en la misma región de AWS que el clúster de Amazon Redshift.

Autorización

El comando UNLOAD necesita autorización para escribir datos en Amazon S3. El comando UNLOAD usa los mismos parámetros que el comando COPY usa para la autorización. Para obtener más información, consulte Parámetros de autorización en la referencia de sintaxis del comando COPY.

[ FORMAT [AS] ] CSV | PARQUET

Cuando CSV, descarga en un archivo de texto en formato CSV utilizando un carácter de coma ( , ) como delimitador predeterminado. Si un campo contiene delimitadores, comillas dobles, caracteres de nueva línea o retornos de carro, el campo en el archivo descargado se encuentra entre comillas dobles. Se aplica escape a un carácter de comillas dobles dentro de un campo de datos mediante un carácter de comillas dobles adicional.

Si es PARQUET, se descarga en un archivo en formato de Apache Parquet versión 1.0. De forma predeterminada, cada grupo de filas se comprime mediante la compresión SNAPPY. Para obtener más información sobre el formato de Apache Parquet, consulte Parquet.

Las palabras clave FORMAT y AS son opcionales. No puede usar CSV con FIXEDWIDTH. No puede utilizar PARQUET con DELIMITER, FIXEDWIDTH, ADDQUOTES, ESCAPE, NULL AS, HEADER, GZIP, BZIP2 o ZSTD. PARQUET con ENCRYPTED solo se admite con el cifrado en el servidor con una clave AWS Key Management Service (SSE-KMS).

PARTITION BY (nombre_columna [, ... ]) [INCLUDE]

Especifica las claves de partición para la operación de descarga. UNLOAD automáticamente particiona los archivos de salida en carpetas de partición basándose en los valores de las claves de partición, siguiendo la convención de la Apache Hive. Por ejemplo, un archivo Parquet que pertenece al año de partición 2019 y al mes de septiembre tiene el siguiente prefijo: s3://my_bucket_name/my_prefix/year=2019/month=September/000.parquet: .

El valor de nombre_columna debe ser una columna en los resultados de consulta que se están descargando.

Si especifica PARTITION BY con la opción INCLUDE, las columnas de partición no se quitarán de los archivos descargados.

Amazon Redshift no admite literales de cadena en cláusulas PARTITION BY.

MANIFEST [ VERBOSE ]

Crea un archivo de manifiesto que enumera explícitamente detalles de los archivos de datos que son creados por el proceso UNLOAD. El manifiesto es un archivo de texto en formato JSON que enumera explícitamente el URL de cada archivo escrito en Amazon S3.

Si se especifica MANIFEST con la opción VERBOSE, el manifiesto incluye los siguientes detalles:

  • Los nombres de columnas y los tipos de datos y, para los tipos de datos CHAR, VARCHAR o NUMERIC, las dimensiones para cada columna. Para los tipos de datos CHAR y VARCHAR, la dimensión es la longitud. Para un tipo de datos DECIMAL o NUMERIC, las dimensiones son la precisión y la escala.

  • La cantidad de filas descargadas en cada archivo. Si se especifica la opción HEADER, la cantidad de filas incluye la línea de encabezado.

  • El tamaño de archivo total de todos los archivos descargados y el recuento de filas total descargadas en todos los archivos. Si se especifica la opción HEADER, el recuento de filas incluye las líneas de encabezado.

  • El autor. El autor es siempre "Amazon Redshift".

Solo puede especificar VERBOSE después de MANIFEST.

El archivo de manifiesto se escribe en el mismo prefijo de ruta de Amazon S3 que los archivos de descarga en el formato <object_path_prefix>manifest. Por ejemplo, si UNLOAD especifica el prefijo de ruta de Amazon S3 "s3://mybucket/venue_", la ubicación del archivo de manifiesto es "s3://mybucket/venue_manifest".

HEADER

Añade una línea de encabezado que contiene los nombres de columna situados al comienzo de cada archivo de salida. Las opciones de transformación de texto, como CSV, DELIMITER, ADDQUOTES y ESCAPE, también se aplican a la línea de encabezado. No puede usar HEADER con FIXEDWIDTH.

DELIMITER AS 'delimiter_character (carácter_delimitador)'

Especifica un carácter ASCII único que se utiliza para separar campos en el archivo de salida, como un carácter de barra vertical ( | ), una coma ( , ) o una tabulación ( \t ). El delimitador predeterminado para los archivos de texto es el carácter de barra vertical. El delimitador predeterminado para los archivos CSV es un carácter de coma. La palabra clave AS es opcional. No puede usar DELIMITER con FIXEDWIDTH. Si los datos contienen el carácter delimitador, necesita especificar la opción ESCAPE para aplicar escape al delimitador, o utilizar ADDQUOTES para encerrar los datos entre comillas dobles. También puede especificar un delimitador que no esté contenido en los datos.

FIXEDWIDTH 'fixedwidth_spec (especificación_de_ancho_fijo)'

Descarga los datos a un archivo donde el ancho de cada columna tiene una longitud fija, en lugar de estar separadas por un delimitador. La cadena fixedwidth_spec (especificación_de_ancho_fijo) especifica la cantidad de columnas y el ancho de las mismas. La palabra clave AS es opcional. Como FIXEDWIDTH no trunca los datos, la especificación de cada columna en la instrucción UNLOAD debe tener al menos la misma longitud que la entrada más larga de esa columna, A continuación, se muestra el formato de fixedwidth_spec (especificación_de_ancho_fijo):

'colID1:colWidth1,colID2:colWidth2, ...'

No puede usar FIXEDWIDTH con DELIMITER o HEADER.

ENCRYPTED [AUTO]

Especifica que los archivos de salida de Amazon S3 se cifran con el cifrado de cliente o de servidor de Amazon S3. Si se especifica MANIFEST, también se cifra el archivo de manifiesto. Para obtener más información, consulte Descarga de archivos de datos cifrados. Si no especifica el parámetro ENCRYPTED, UNLOAD crea automáticamente archivos cifrados a través del cifrado de servidor de Amazon S3, con claves de cifrado administradas por AWS (SSE-S3).

Para ENCRYPTED, es posible que desee descargar en Amazon S3 usando el cifrado del lado del servidor con una clave de AWS KMS (SSE-KMS). Si es así, utilice el parámetro KMS_KEY_ID para proporcionar el ID de la clave. No puede utilizar el parámetro CREDENTIALS con el parámetro KMS_KEY_ID. Si ejecuta un comando UNLOAD para datos mediante KMS_KEY_ID, puede realizar una operación COPY para los mismos datos sin especificar una clave.

Para descargar en Amazon S3 usando el cifrado del lado del cliente con una clave simétrica proporcionada por el cliente (CSE-CMK), proporcione la clave de una de estas dos maneras. Para proporcionar la clave, utilice el parámetro MASTER_SYMMETRIC_KEY o la parte master_symmetric_key de una cadena de credenciales CREDENTIALS. Si descarga datos con una clave simétrica maestra, asegúrese de proporcionar la misma clave cuando realice una operación COPY para los datos cifrados.

UNLOAD no admite el cifrado de servidor de Amazon S3 con una clave proporcionada por el cliente (SSE-C).

Si se utiliza ENCRYPTED AUTO, el comando UNLOAD obtiene la clave de cifrado KMS predeterminada en la propiedad del bucket de Amazon S3 de destino y cifra los archivos escritos en Amazon S3 con la clave KMS. Si el bucket no tiene la clave de cifrado KMS predeterminada, UNLOAD crea automáticamente archivos cifrados mediante el cifrado del lado del servidor Amazon Redshift con claves de cifrado administradas por AWS (SSE-S3). No puede utilizar esta opción con KMS_KEY_ID, MASTER_SYMMETRIC_KEY ni CREDENTIALS que contiene master_symmetric_key.

KMS_KEY_ID 'key-id (identificador-de-clave)'

Especifica el ID de una clave de AWS Key Management Service (AWS KMS) que se utiliza para cifrar archivos de datos en Amazon S3. Para obtener más información, consulte ¿Qué es AWS Key Management Service? Si especifica KMS_KEY_ID, también debe especificar el parámetro ENCRYPTED. Si especifica KMS_KEY_ID, no puede autenticar con el parámetro CREDENTIALS. En su lugar, utilice IAM_ROLE o ACCESS_KEY_ID and SECRET_ACCESS_KEY.

MASTER_SYMMETRIC_KEY 'master_key (clave_maestra)'

Especifica la clave maestra simétrica que se utiliza para cifrar archivos de datos en Amazon S3. Si especifica MASTER_SYMMETRIC_KEY, también debe especificar el parámetro ENCRYPTED. No puede utilizar MASTER_SYMMETRIC_KEY con el parámetro CREDENTIALS. Para obtener más información, consulte Carga de archivos de datos cifrados desde Amazon S3.

BZIP2

Descarga datos en uno o más archivos comprimidos en bzip2 por sector. Cada archivo resultante se adjunta con una extensión .bz2.

GZIP

Descarga datos en uno o más archivos comprimidos en gzip por sector. Cada archivo resultante se adjunta con una extensión .gz.

ZSTD

Descarga datos en uno o más archivos comprimidos en Zstandard por sector. Cada archivo resultante se adjunta con una extensión .zst.

ADDQUOTES

Coloca comillas alrededor de cada campo de datos no descargado para que Amazon Redshift pueda descargar los valores de datos que contienen el delimitador. Por ejemplo, si el delimitador es una coma, podría descargar y volver a cargar los siguientes datos de manera correcta:

"1","Hello, World"

Sin las comillas añadidas, la cadena Hello, World se analizaría como dos campos separados.

Si utiliza ADDQUOTES, debe especificar REMOVEQUOTES en el comando COPY si vuelve a cargar los datos.

NULL AS 'null-string (cadena_null)'

Especifica una cadena que representa un valor nulo en archivos de descarga. Si se utiliza esta opción, todos los archivos de salida contienen la cadena especificada en lugar de valores nulos encontrados en los datos seleccionados. Si no se especifica esta opción, los valores nulos se descargan como:

  • Cadenas de longitud cero para un resultado delimitado

  • Cadenas con espacios en blanco para un resultado de ancho fijo

Si se especifica una cadena nula para una descarga de ancho fijo, y el ancho de una columna de resultado es menor que el ancho de la cadena nula, ocurre el siguiente comportamiento:

  • Un campo vacío es el resultado para columnas sin caracteres

  • Se reporta un error para columnas con caracteres

A diferencia de otros tipos de datos en los que una cadena definida por el usuario representa un valor nulo, Amazon Redshift exporta las columnas de datos SUPER con el formato JSON y lo representa como nulas según lo determinado por el formato JSON. Como resultado, las columnas de datos SUPER ignoran la opción NULL [AS] utilizada en los comandos UNLOAD.

ESCAPE

Para las columnas CHAR y VARCHAR en archivos de descarga delimitados, se coloca un carácter de escape (\) antes de cada ocurrencia de los siguientes caracteres:

  • Salto de línea: \n

  • Retorno de carro: \r

  • El carácter delimitador especificado para los datos descargados.

  • El carácter de escape: \

  • Un carácter de comillas: " o ' (si se especifican ESCAPE y ADDQUOTES en el comando UNLOAD).

importante

Si cargó los datos a través de un comando COPY con la opción ESCAPE, también debe especificar la opción ESCAPE con el comando UNLOAD para generar el archivo de salida recíproco. De manera similar, si utiliza UNLOAD con la opción ESCAPE, necesita usar ESCAPE cuando aplica COPY en los mismos datos.

ALLOWOVERWRITE

Por defecto, UNLOAD produce un error si encuentra archivos que podría sobrescribir. Si se especifica ALLOWOVERWRITE, UNLOAD sobrescribe los archivos existentes, incluido el archivo de manifiesto.

PARALLEL

Por defecto, el comando UNLOAD escribe datos simultáneamente en varios archivos, según la cantidad de sectores que haya en el clúster. La opción predeterminada es ON o TRUE. Si PARALLEL es OFF o FALSE, UNLOAD escribe en uno o más archivos de datos en serie, ordenados absolutamente en función de la cláusula ORDER BY, si se utiliza una. El tamaño máximo de un archivo de datos es de 6,2 GB. Por ejemplo, si descarga 13,4 GB de datos, UNLOAD crea los siguientes tres archivos.

s3://mybucket/key000 6.2 GB s3://mybucket/key001 6.2 GB s3://mybucket/key002 1.0 GB
nota

El comando UNLOAD está diseñado para utilizar procesamiento en paralelo. Le recomendamos dejar PARALLEL habilitado para la mayoría de casos, especialmente si los archivos se utilizan para cargar tablas mediante un comando COPY.

MAXFILESIZE [AS] max-size [ MB | GB ]

Especifica el tamaño máximo de los archivos que UNLOAD crea en Amazon S3. Especifique un valor decimal entre 5 MB y 6,2 GB. La palabra clave AS es opcional. La unidad predeterminada es MB. Si no se especifica MAXFILESIZE, el tamaño máximo predeterminado de un archivo es de 6,2 GB. El tamaño del archivo de manifiesto, si se utiliza uno, no se ve afectado por MAXFILESIZE.

REGION [AS] 'aws_region (región_de_aws)'

Especifica la región de AWS donde está ubicado el bucket de Amazon S3 de destino. REGION es obligatorio para realizar la operación UNLOAD en un bucket de Amazon S3 que no está en la misma región de AWS que el clúster de Amazon Redshift.

El valor de aws_region debe coincidir con una región de AWS enumerada en la tabla regiones y puntos de enlace de Amazon Redshift de la Referencia general de AWS.

Por defecto, UNLOAD presupone que el bucket de Amazon S3 de destino está ubicado en la misma región de AWS que el clúster de Amazon Redshift.

Notas de uso

Uso de ESCAPE para todas las operaciones UNLOAD de texto delimitado

Cuando utiliza UNLOAD con un delimitador, sus datos pueden incluir ese delimitador o cualquiera de los caracteres enumerados en la descripción de la opción ESCAPE. En este caso, debe usar la opción ESCAPE con la instrucción UNLOAD. Si no utiliza la opción ESCAPE con UNLOAD, las operaciones de COPY subsiguientes que utilicen datos descargados producirán un error.

importante

Le recomendamos encarecidamente que siempre use ESCAPE con ambas instrucciones UNLOAD y COPY. Solo puede saltarse esta regla si sabe con seguridad que los datos no contienen delimitadores u otros caracteres que puedan necesitar escape.

Pérdida de precisión de punto flotante

Puede enfrentarse a una pérdida de precisión para datos de punto flotante que se descargan y vuelven a cargar de manera sucesiva.

Cláusula de límite

La consulta SELECT no puede utilizar una cláusula LIMIT en SELECT externo. Por ejemplo, la siguiente instrucción UNLOAD produce un error.

unload ('select * from venue limit 10') to 's3://mybucket/venue_pipe_' iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole';

En su lugar, use una cláusula LIMIT anidada, como en el siguiente ejemplo.

unload ('select * from venue where venueid in (select venueid from venue order by venueid desc limit 10)') to 's3://mybucket/venue_pipe_' iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole';

También puede rellenar una tabla con SELECT…INTO o CREATE TABLE AS a través de una cláusula LIMIT y, luego, descargar desde esa tabla.

Descarga de una columna de tipo de datos GEOMETRY

Solo puede descargar columnas GEOMETRY para texto o formato CSV. No puede descargas datos GEOMETRY con la opción FIXEDWIDTH. Los datos se descargan en forma hexadecimal del formato binario conocido extendido (EWKB). Si el tamaño de los datos EWKB es mayor de 4 MB, se producirá una advertencia porque los datos no se podrán luego cargar en una tabla.

Descarga del tipo de datos HLLSKETCH

Solo puede descargar columnas HLLSKETCH en formato de texto o CSV. No puede descargar datos de HLLSKETCH con la opción FIXEDWIDTH. Los datos se descargan en formato Base64 para cadenas HyperLogLog densas o en formato JSON para cadenas HyperLogLog dispersas. Para obtener más información, consulte Funciones deHyperLogLog.

El siguiente ejemplo exporta una tabla que contiene columnas HLLSKETCH a un archivo.

CREATE TABLE a_table(an_int INT, b_int INT); INSERT INTO a_table VALUES (1,1), (2,1), (3,1), (4,1), (1,2), (2,2), (3,2), (4,2), (5,2), (6,2); CREATE TABLE hll_table (sketch HLLSKETCH); INSERT INTO hll_table select hll_create_sketch(an_int) from a_table group by b_int; UNLOAD ('select * from hll_table') TO 's3://mybucket/unload/' IAM_ROLE 'arn:aws:iam::0123456789012:role/MyRedshiftRole' NULL AS 'null' ALLOWOVERWRITE CSV;

Cláusula FORMAT AS PARQUET

Tenga en cuenta estas consideraciones al usar FORMAT AS PARQUET:

  • La descarga en Parquet no utiliza la compresión de nivel de archivo. Cada grupo de filas se comprime con SNAPPY.

  • Si no se especifica MAXFILESIZE, el tamaño máximo predeterminado de un archivo es de 6,2 GB. Puede utilizar MAXFILESIZE para especificar un tamaño de archivo de 5 MB–6,2 GB. El tamaño real del archivo es aproximado cuando se está escribiendo el archivo, por lo que es posible que no sea exactamente igual al número que especifique.

    Para maximizar el rendimiento del análisis, Amazon Redshift intenta crear archivos Parquet que contengan grupos de filas de 32 MB del mismo tamaño. El valor MAXFILESIZE que especifique se redondea automáticamente al múltiplo más cercano de 32 MB. Por ejemplo, si especifica MAXFILESIZE 200 MB, cada archivo Parquet descargado es de aproximadamente 192 MB (grupo de filas de 32 MB x 6 = 192 MB).

  • Si una columna utiliza el formato de datos TIMESTAMPTZ, solo se descargan los valores de marca temporal. La información de zona horaria no se descarga.

  • No especifique prefijos de nombre de archivo que comiencen con caracteres de subrayado (_) o de punto (.). Redshift Spectrum trata los archivos que comienzan con estos caracteres como archivos ocultos y los omite.

Cláusula PARTITION BY

Tenga en cuenta estas consideraciones al usar PARTITION BY:

  • Las columnas de partición no se incluyen en el archivo de salida.

  • Asegúrese de incluir las columnas de partición en la consulta SELECT utilizada en la instrucción UNLOAD. Puede especificar cualquier número de columnas de partición en el comando UNLOAD. Sin embargo, existe una limitación de que debe haber al menos una columna que no sea de partición para formar parte del archivo.

  • Si el valor de la clave de partición es nulo, Amazon Redshift descarga automáticamente esos datos en una partición predeterminada llamada partition_column=__HIVE_DEFAULT_PARTITION__.

  • El comando UNLOAD no realiza ninguna llamada a un catálogo externo. Para registrar las nuevas particiones para que formen parte de la tabla externa existente, use un comando ALTER ... ADD PARTITION ... independiente. O puede ejecutar un comando CREATE EXTERNAL TABLE para registrar los datos descargados como una nueva tabla externa. También puede utilizar un rastreador AWS Glue para rellenar su Data Catalog. Para obtener más información, consulte Definición de rastreadores en la Guía para desarrolladores de AWS Glue.

  • Si utiliza la opción MANIFEST, Amazon Redshift solo generará un archivo de manifiesto en la carpeta raíz de Amazon S3.

  • Los tipos de datos de columna que puede utilizar como clave de partición son SMALLINT, INTEGER, BIGINT, DECIMAL, REAL, BOOLEAN, CHAR, VARCHAR, DATE y TIMESTAMP.

Usar el privilegio ASSUMEROLE para conceder acceso a una función de IAM para operaciones UNLOAD

Para proporcionar acceso a usuarios y grupos específicos a una función de IAM para operaciones UNLOAD, un superusuario puede otorgar el privilegio ASSUMEROLE en una función de IAM a usuarios y grupos. Para obtener información, consulte GRANT.