UNLOAD

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')

('select * from venue where venuestate=''NV''')

Se trata de la ruta completa, incluido el nombre del bucket, a la ubicación en Amazon S3 donde Amazon Redshift escribe los objetos del archivo de salida, incluido el archivo de manifiesto si se especifica MANIFEST. Los nombres del objeto tienen el prefijo name-prefix. Si utiliza PARTITION BY, se agrega 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 agrega 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.

Si se especifica PARALLEL en OFF, los archivos de datos se escriben de la siguiente manera:

<object_path>/<name_prefix><part-number>.

UNLOAD crea de forma automática archivos cifrados a través del cifrado del lado del 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 lado del servidor desde el bucket a través de la API o la consola de Amazon S3. Para obtener más información, consulte Protección de los datos con el cifrado del servidor.

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

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.

Utilice la palabra clave predeterminada para que Amazon Redshift utilice el rol de IAM configurado como predeterminado y asociado al clúster cuando se ejecuta el comando UNLOAD.

Utilice el nombre de recurso de Amazon (ARN), de un rol de IAM que el clúster utiliza para la autenticación y la autorización. Si especifica IAM_ROLE, no puede utilizar ACCESS_KEY_ID, SECRET_ACCESS_KEY, SESSION_TOKEN ni CREDENTIALS. El IAM_ROLE se puede encadenar. Para obtener más información, consulte Encadenar roles de IAM en la Guía de administración de Amazon Redshift.

Se trata de las palabras clave para especificar el formato de descarga con objeto de anular el formato predeterminado.

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. Cuando se descargan cero filas, es posible que Amazon Redshift escriba objetos de Amazon S3 vacíos.

Si es PARQUET, se descarga en un archivo en formato de Apache Parquet versión 1.0. De manera 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.

Si es JSON, se descarga en un archivo JSON con cada línea que contiene un objeto JSON, lo que representa un registro completo en el resultado de la consulta. Amazon Redshift admite escribir JSON anidado cuando el resultado de la consulta contiene columnas SUPER. Para crear un objeto JSON válido, el nombre de cada columna de la consulta debe ser único. En el archivo JSON, los valores booleanos se descargan como t o f, y los valores NULL se descargan como null. Cuando se descargan cero filas, Amazon Redshift no escribe objetos de Amazon S3.

Las palabras clave FORMAT y AS son opcionales. No puede usar CSV con FIXEDWIDTH ni ADDQUOTES. 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). No puede utilizar JSON con DELIMITER, HEADER, FIXEDWIDTH, ADDQUOTES, ESCAPE, o NULL AS.

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://amzn-s3-demo-bucket/my_prefix/year=2019/month=September/000.parquet.

El valor de column_name 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.

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 las direcciones URL de cada archivo escrito en Amazon S3.

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

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 “s3://amzn-s3-demo-bucket/venue_” de Amazon S3, la ubicación del archivo de manifiesto es “s3://amzn-s3-demo-bucket/venue_manifest”.

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

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

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

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

No puede usar FIXEDWIDTH con DELIMITER o HEADER.

Especifica que los archivos de salida en Amazon S3 se cifran con cifrado del lado del servidor y del lado del cliente 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 de forma automática archivos cifrados a través del cifrado del lado del servidor de Amazon S3, con claves de cifrado administradas por AWS (SSE-S3).

Para ENCRYPTED, es posible que desee descargar el contenido en Amazon S3 mediante 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 el contenido en Amazon S3 a través del cifrado del lado del cliente con una clave simétrica proporcionada por el cliente, proporcione la clave a través 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 raíz simétrica, asegúrese de proporcionar la misma clave cuando realice una operación COPY para los datos cifrados.

UNLOAD no es compatible con el cifrado del lado del 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 de AWS KMS predeterminada en la propiedad del bucket de Amazon S3 de destino y cifra los archivos escritos en Amazon S3 con la clave de AWS KMS. Si el bucket no tiene la clave de cifrado de AWS KMS predeterminada, UNLOAD crea automáticamente archivos cifrados a través del cifrado del lado del servidor de 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.

Especifica el ID de una clave de AWS Key Management Service (AWS KMS) que se utilizará 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.

Especifica la clave raíz simétrica que se utilizará 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.

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

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

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

Coloca comillas alrededor de cada campo de datos descargado para que Amazon Redshift pueda descargar los valores de datos que contienen el propio 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 agregadas, la cadena Hello, World se analizaría como dos campos separados.

Algunos formatos de salida no admiten ADDQUOTES.

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

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:

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:

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 mediante el formato JSON y lo representa como nulo, de acuerdo con lo determinado por el formato JSON. Como resultado, las columnas de datos SUPER ignoran la opción NULL [AS] utilizada en los comandos UNLOAD.

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:

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.

La opción CLEANPATH quita los archivos existentes ubicados en la ruta de Amazon S3 especificada en la cláusula TO antes de descargar archivos en la ubicación determinada.

Si incluye la cláusula PARTITION BY, los archivos existentes se quitan solo de las carpetas de partición para recibir archivos nuevos generados por la operación UNLOAD.

Debe tener el permiso s3:DeleteObject en el bucket de Amazon S3. Para obtener información, consulte Políticas y permisos en Amazon S3 en la Guía del usuario de Amazon Simple Storage Service. Los archivos que quita con la opción CLEANPATH se eliminan de forma permanente y no se pueden recuperar. Si el bucket de Amazon S3 de destino tiene activado el control de versiones, UNLOAD con la opción CLEANPATH no elimina las versiones anteriores de los archivos.

No se puede especificar la opción CLEANPATH si ya se especificó la opción ALLOWOVERWRITE.

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://amzn-s3-demo-bucket/key000    6.2 GB
s3://amzn-s3-demo-bucket/key001    6.2 GB
s3://amzn-s3-demo-bucket/key002    1.0 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.

Especifica el tamaño de los grupos de filas. La elección de un tamaño mayor puede reducir el número de grupos de filas y reducir la cantidad de comunicación de red. Especifique un valor entero entre 32 MB y 128 MB. La palabra clave AS es opcional. La unidad predeterminada es MB.

Si no se especifica ROWGROUPSIZE, el tamaño predeterminado es 32 MB. Para utilizar este parámetro, el formato de almacenamiento debe ser Parquet y el tipo de nodo debe ser ra3.4xlarge, ra3.16xlarge o dc2.8xlarge.

Especifica la Región de AWS donde está ubicado el bucket de Amazon S3 de destino. REGION es obligatorio para la operación UNLOAD en un bucket de Amazon S3 que no esté en la misma Región de AWS que la base de datos de Amazon Redshift.

El valor de aws_region debe coincidir con una región de AWS incluida en la tabla Regiones y puntos de conexión de Amazon Redshift en la Referencia general de AWS.

De manera predeterminada, UNLOAD asume que el bucket de Amazon S3 de destino se encuentra en la misma Región de AWS que la base de datos de Amazon Redshift.

Especifica la extensión del archivo que se va a agregar a los nombres de los archivos descargados. Amazon Redshift no ejecuta ninguna validación, por lo que debe comprobar que la extensión de archivo especificada es correcta. Si utiliza un método de compresión como GZIP, aún tiene que especificar .gz en el parámetro de extensión. Si no proporciona ninguna extensión, Amazon Redshift no agrega nada al nombre del archivo. Si especifica un método de compresión sin proporcionar una extensión, Amazon Redshift solo agrega la extensión del método de compresión al nombre del archivo.