UNLOAD

Amazon S3 サーバー側暗号化 (SSE-S3) 機能を使用して Amazon S3 の 1 つ以上のテキストファイルまたは Apache Parquet ファイルに対するクエリの結果をアンロードします。AWS Key Management Service キーを使用したサーバー側の暗号化 (SSE-KMS)、またはカスタマーマネージドキーを使用したクライアント側の暗号化 (CSE-CMK) を指定することもできます。

デフォルトでは、アンロードされたファイルの形式はパイプ区切り (|) テキストです。

Amazon S3 のファイルは、サイズ、拡張子、ファイル数、MAXFILESIZE パラメータを設定することで管理できます。

分析用の効率的なオープン列型ストレージ形式である Apache Parquet では、Amazon Redshift クエリの結果を Amazon S3 データレイクにアンロードできます。Parquet 形式は、テキスト形式と比較して、アンロードが最大 2 倍速く、さらにストレージ使用量が Amazon S3 で最大 6 倍少なくすみます。これにより、Amazon S3 で行ったデータ変換とエンリッチメントをオープン形式で Amazon S3 データレイクに保存できます。その後、Redshift Spectrum や Amazon Athena、Amazon EMR、SageMaker などの他の AWS のサービスを使用してデータを分析できます。

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
| CLEANPATH
| PARALLEL [ { ON | TRUE } | { OFF | FALSE } ]
| MAXFILESIZE [AS] max-size [ MB | GB ] 
| REGION [AS] 'aws-region' }

Parameters

('select-statement')

SELECT クエリ。クエリ結果をアンロードします。ほとんどの場合、クエリで ORDER BY 句を指定してソート順にデータをアンロードすることは有益です。この方法は、データの再ロード時にデータをソートするために必要な時間を節約します。

クエリは、次に示すように一重引用符で囲む必要があります:


('select * from venue order by venueid')

注記

クエリに引用符が含まれている場合 (リテラル値を囲む場合など)、リテラルを 2 つの単一引用符で囲みます。また、クエリを単一引用符で囲む必要があります。


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

TO 's3://object-path/name-prefix'

Amazon Redshift が出力ファイルオブジェクト (MANIFEST が指定されている場合はマニフェストファイルを含む) を書き込む Amazon S3 上の絶対パス (バケット名を含む)。オブジェクト名には name-prefix というプレフィックスが付きます。PARTITION BY を使用すると、必要に応じて name-prefix 値の末尾にスラッシュ (/) が自動的に追加されます。さらにセキュリティを強化するために、UNLOAD は HTTPS 接続を使用して Amazon S3 に接続します。デフォルトでは、UNLOAD はスライスごとに 1 つ以上のファイルを書き込みます。次に示すように、UNLOAD は指定された名前のプレフィックスにスライス番号とパート番号を追加します:

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

MANIFEST が指定された場合、マニフェストファイルは次のように書き込まれます:

<object_path>/<name_prefix>manifest.

UNLOAD は、Amazon S3 サーバー側の暗号化 (SSE) を使用して自動的に暗号化ファイルを作成します。MANIFEST を使用すると、マニフェストファイルも暗号化されます。COPY コマンドは、ロード操作中に自動的にサーバー側で暗号化されたファイルを読み取ります。Amazon S3 マネジメントコンソールまたは API を使用すると、サーバー側で暗号化されたファイルをバケットから透過的にダウンロードできます。詳細については、「サーバー側の暗号化を使用したデータの保護」を参照してください。

Amazon S3 クライアント側暗号化機能を使用するには、ENCRYPTED オプションを指定します。

重要

REGION は、Amazon S3 バケットが Amazon Redshift クラスターと同じ AWS リージョンにない場合に必須です。

承認

UNLOAD コマンドには Amazon S3 にデータを書き込むための認証が必要です。UNLOAD コマンドは、COPY コマンドが認証に使用するのと同じパラメータを使用します。詳細については、COPY コマンドの構文リファレンスの「認証パラメータ」を参照してください。

[ FORMAT [AS] ] CSV | PARQUET

デフォルトの形式を上書きするアンロード形式を指定するキーワード。

CSV の場合、デフォルトの区切り文字としてカンマ (,) を使用して CSV 形式でテキストファイルをアンロードします。フィールドに区切り文字、二重引用符、改行文字、またはキャリッジリターンが含まれている場合、アンロードしたファイルのフィールドは二重引用符で囲まれます。データフィールド内の二重引用符は、追加の二重引用符でエスケープされます。

PARQUET の場合、Apache Parquet バージョン 1.0 形式のファイルにアンロードします。デフォルトでは、各行グループは SNAPPY 圧縮を使用して圧縮されます。Apache Parquet 形式の詳細については、「Apache Parquet」を参照してください。

キーワード FORMAT および AS はオプションです。CSV は FIXEDWIDTH と併用できません。DELIMITER、FIXEDWIDTH、ADDQUOTES、ESCAPE、NULL AS、HEADER、GZIP、BZIP2、ZSTD では、PARQUET を使用できません。ENCRYPTED を使用した PAREQUET は、AWS Key Management Service Key (SSE-KMS) を使用したサーバー側の暗号化でのみサポートされます。

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

アンロードオペレーションのパーティションキーを指定します。UNLOAD は、Apache Hive の規則に従って、パーティションキーの値に基づいて、出力ファイルをパーティションフォルダに自動的に分割します。たとえば、パーティション year 2019 および month September に属する Parquet ファイルには、次のプレフィックス s3://my_bucket_name/my_prefix/year=2019/month=September/000.parquet があります。

column_name の値は、アンロードされるクエリ結果の列である必要があります。

PARTITION BY で INCLUDE オプションを指定すると、アンロードされるファイルからパーティション列が削除されません。

Amazon Redshift は、PARTITION BY 句で文字列リテラルをサポートしていません。

MANIFEST [ VERBOSE ]

UNLOAD プロセスによって作成されたデータファイルの詳細を明示的に一覧表示するマニフェストファイルを作成します。マニフェストは、Amazon S3 に書き込まれた各ファイルの URL をリストする、JSON 形式のテキストファイルです。

MANIFEST が VERBOSE オプションとともに指定されている場合、マニフェストには以下の詳細が含まれます。

列名とデータ型、および CHAR、VARCHAR、または NUMERIC データ型の場合は各列のディメンション。CHAR および VARCHAR データ型の場合、ディメンションは長さです。DECIMAL または NUMERIC データ型の場合、ディメンションは精度とスケールです。
各ファイルにアンロードされた行数。HEADER オプションが指定されている場合、行数にはヘッダー行が含まれます。
アンロードされたすべてのファイルの合計ファイルサイズ、およびすべてのファイルにアンロードされた合計行数。HEADER オプションが指定されている場合、行数にはヘッダー行が含まれます。
作成者。作成者は常に「Amazon Redshift」です。

VERBOSE は、MANIFEST の後にしか指定できません。

マニフェストファイルは、アンロードファイルと同じ Amazon S3 パスプレフィックスに <object_path_prefix>manifest 形式で書き込まれます。たとえば、UNLOAD で Amazon S3 パスプレフィックス 's3://mybucket/venue_' が指定されている場合、マニフェストファイルの場所は 's3://mybucket/venue_manifest' となります。

HEADER

各出力ファイルの先頭に列名を含むヘッダー行を追加します。CSV、DELIMITER、ADDQUOTES、ESCAPE などのテキスト変換オプションもヘッダー行に適用されます。HEADER は FIXEDWIDTH と併用できません。

DELIMITER AS 'delimiter_character'

パイプ文字 (|)、カンマ (,)、タブ (\t) など、出力ファイルのフィールドを区切るために使用する単一の ASCII 文字を指定します。テキストファイルのデフォルトの区切り文字はパイプ文字です。CSV ファイルのデフォルトの区切り文字はコンマ文字です。AS キーワードはオプションです。DELIMITER は FIXEDWIDTH と併用できません。データに区切り文字が含まれている場合、ESCAPE オプションを指定して、区切り文字をエスケープするか、ADDQUOTES を使って、データを二重引用符で囲む必要があります。代替案として、データ内に含まれていない区切り文字を指定します。

FIXEDWIDTH 'fixedwidth_spec'

区切り文字によって区切られているのではなく、各列の幅が固定長のファイルにデータをアンロードします。fixedwidth_spec は、列の数と列の幅を指定する文字列です。AS キーワードはオプションです。FIXEDWIDTH はデータを切り捨てないため、UNLOAD ステートメントの各列の指定は、少なくともその列の最長エントリの長さと同じになります。fixedwidth_spec の形式を次に示します。


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

FIXEDWIDTH は DELIMITER または HEADER と併用できません。

ENCRYPTED [AUTO]

Amazon S3 上の出力ファイルは、Amazon S3 サーバー側の暗号化機能またはクライアント側の暗号化機能を使って暗号化されるよう指定します。MANIFEST を指定すると、マニフェストファイルも暗号化されます。詳細については、「」を参照してください暗号化されたデータファイルをアンロードする ENCRYPTED パラメータを指定しない場合、UNLOAD は AWS マネージド暗号化キーを使用した Amazon S3 サーバー側の暗号化 (SSE-S3) 機能を使用して、暗号化済みファイルを作成します。

ENCRYPTED では、AWS KMS キーでサーバー側の暗号化 (SSE-KMS) を使用して Amazon S3 にアンロードすることができます。その場合は、KMS_KEY_ID パラメータを使用してキー ID を指定します。CREDENTIALS パラメータを KMS_KEY_ID パラメータと併用することはできません。KMS_KEY_ID を使用してデータに対して UNLOAD コマンドを実行すると、キーを指定せずに同じデータに対して COPY オペレーションを実行できます。

お客様が提供した対称キー (CSE-CMK) とクライアント側の暗号化を使用して Amazon S3 にアンロードするには、2 つの方法のいずれかでキーを指定します。キーを提供するには、MASTER_SYMMETRIC_KEY パラメータまたは master_symmetric_key 認証情報文字列の CREDENTIALS 部分を使用します。マスター対称キーを使用してデータをアンロードする場合は、暗号化されたデータに対して COPY オペレーションを実行するときに、必ず同じキーを指定します。

UNLOAD では、お客様が用意したキー (SSE-C) による Amazon S3 サーバー側の暗号化はサポートされません。

ENCRYPTED AUTO が使用されている場合、UNLOAD コマンドはターゲット Amazon S3 バケットプロパティ上のデフォルトの KMS 暗号化キーを取得し、Amazon S3 に書き込まれたファイルを AWS KMS キーで暗号化します。バケットにデフォルトの AWS KMS 暗号化キーがない場合、UNLOAD は AWS マネージド暗号化キー (SSE-S3) を使用した Amazon Redshift サーバー側の暗号化を使用して、暗号化されたファイルを自動的に作成します。このオプションは、master_symmetric_key を含む KMS_KEY_ID、MASTER_SYMMETRIC_KEY、または CREDENTIALS では使用できません。

KMS_KEY_ID 'key-id'

Amazon S3 のデータファイルの暗号化に使用する AWS Key Management Service (AWS KMS) キーのキー ID を指定します。詳細については、「AWS Key Management Service とは」を参照してください。KMS_KEY_ID を指定する場合、ENCRYPTED パラメータも指定する必要があります。KMS_KEY_ID を指定する場合、CREDENTIALS パラメータを使用して認証することはできません。代わりに IAM_ROLE または ACCESS_KEY_ID and SECRET_ACCESS_KEY のどちらかを使用します。

MASTER_SYMMETRIC_KEY 'master_key'

Amazon S3 上のデータファイルの暗号化に使用するマスター対称キーを指定します。MASTER_SYMMETRIC_KEY を指定する場合、ENCRYPTED パラメータも指定する必要があります。MASTER_SYMMETRIC_KEY は CREDENTIALS パラメータと併用できません。詳細については、「」を参照してください暗号化されたデータファイルを Amazon S3 からロードする

BZIP2

スライスごとに、1 つまたは複数の bzip2 圧縮ファイルにデータをアンロードします。生成される各ファイルには、.bz2 拡張子が付加されます。

GZIP

スライスごとに、1 つまたは複数の gzip 圧縮ファイルにデータをアンロードします。生成される各ファイルには、.gz 拡張子が付加されます。

ZSTD

スライスごとに、1 つまたは複数の Zstandard 圧縮ファイルにデータをアンロードします。生成される各ファイルには、.zst 拡張子が付加されます。

ADDQUOTES

アンロードされた各データフィールドは引用符で囲まれるため、Amazon Redshift は区切り文字自体を含んでいるデータ値をアンロードすることができます。たとえば、区切りがカンマの場合、次のデータのアンロードと再ロードを完了することができます。


 "1","Hello, World"

追加した引用符がない場合、文字列 Hello, World は 2 つの異なるフィールドとして解析されます。

ADDQUOTES を使用した際にデータを再ロードするには、COPY で REMOVEQUOTES を指定する必要があります。

NULL AS 'null-string'

アンロードファイル内で NULL 値を表す文字列を指定します。このオプションを使用すると、選択したデータ内で検出された NULL 値の代わりに、指定した文字列がすべての出力ファイルに挿入されます。このオプションを指定しない場合、NULL 値は次のようにアンロードされます。

区切り文字で区切られた出力に対するゼロ長文字列
固定幅出力に対するホワイトスペース文字列

固定幅のアンロードに対して NULL 文字列が指定され、出力列の幅が NULL 文字列の幅より小さい場合、次の動作が発生します。

空のフィールドは非文字列用の出力です。
文字列に対してはエラーがレポートされます。

ユーザー定義の文字列が null 値を表す他のデータ型とは異なり、Amazon Redshift は JSON 形式を使用して SUPER データ列をエクスポートし、JSON 形式で決定されるように null として表します。その結果、SUPER データ列では、UNLOAD コマンドで使用される NULL [AS] オプションを無視します。

ESCAPE

区切られたアンロードファイル内の CHAR と VARCHAR 列の場合、エスケープ文字 (\) が次の文字の前に必ず配置されます。

ラインフィード: \n
キャリッジリターン: \r
アンロードデータ用に指定された区切り文字。
エスケープ文字: \
引用符: " または ' (ESCAPE と ADDQUOTES の両方を UNLOAD コマンドで指定した場合)。

重要

ESCAPE オプションを指定して COPY を使ってデータをロードした場合、UNLOAD コマンドでも ESCAPE オプションを指定して可逆出力ファイルを生成する必要があります。同様に、ESCAPE オプションを使って UNLOAD を実行すると、同じデータを COPY する場合に ESCAPE を使用する必要があります。

ALLOWOVERWRITE

デフォルトでは、UNLOAD によってファイルの上書きが発生する可能性がある場合、その UNLOAD 操作は失敗します。ALLOWOVERWRITE が指定された場合、UNLOAD によって、マニフェストファイルを含めた既存のファイルが上書きされます。

CLEANPATH

CLEANPATH オプションは、TO 句で指定された Amazon S3 パスにある既存のファイルを削除してから、指定した場所にファイルをアンロードします。

PARTITION BY 句を含めると、既存のファイルはパーティションフォルダからのみ削除され、UNLOAD オペレーションによって生成された新しいファイルを受信します。

Amazon S3 バケットでの s3:DeleteObject 許可が必要です。詳細については、Amazon Simple Storage Service ユーザーガイドの Amazon S3 でのポリシーと許可を参照してください。CLEANPATH オプションを使用して削除したファイルは、完全に削除され、復元することはできません。

ALLOWOVERWRITE オプションを指定した場合、CLEANPATH オプションを指定することはできません。

PARALLEL

デフォルトでは、UNLOAD は、クラスター内のスライスの数に応じて、データを複数のファイルに同時に書き込みます。デフォルトのオプションは ON または TRUE です。PARALLEL が OFF または FALSE の場合、UNLOAD は、ORDER BY 句が使用される場合はそれに従って絶対的にソートされた 1 つ以上のデータファイルに逐次書き込みます。データファイルの最大サイズは 6.2 GB です。したがって、たとえば、13.4 GB のデータをアンロードする場合、UNLOAD は以下の 3 つのファイルを作成します。


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

注記

UNLOAD コマンドは、並列処理を使用するように設計されています。特別な理由がなく、特にファイルが COPY コマンドを使用してテーブルをロードするために使用される場合には、PARALLEL を有効にしたままにすることをお勧めします。

MAXFILESIZE [AS] 最大サイズ [ MB | GB ]

UNLOAD によって Amazon S3 で作成されるファイルの最大サイズを指定します。5 MB ～ 6.2 GB の十進値を指定します。AS キーワードはオプションです。デフォルト単位は MB です。MAXFILESIZE を指定しない場合、デフォルトの最大ファイルサイズは 6.2 GB です。マニフェストファイルが使用されている場合、このサイズは MAXFILESIZE に影響されません。

REGION [AS] 'aws-region'

ターゲットの Amazon S3 バケットがある AWS リージョンを指定します。Amazon Redshift クラスターと同じ AWS リージョンにない Amazon S3 バケットへの UNLOAD には REGION が必要です。

aws_region の値は、AWS の全般的なリファレンスから Amazon Redshift リージョンおよびエンドポイントのテーブルに記載されている AWS リージョンと一致する必要があります。

デフォルトでは、UNLOAD はターゲットの Amazon S3 バケットが Amazon Redshift クラスターと同じ AWS リージョンにあると見なします。

使用に関する注意事項

区切り文字が使われているすべての UNLOAD 操作に対する ESCAPE の使用

区切り文字を使用して UNLOAD する場合、データにはその区切り文字、または ESCAPE オプションの説明に一覧表示されている任意の文字を含めることができます。この場合は、UNLOAD ステートメントで ESCAPE オプションを使用する必要があります。UNLOAD コマンドで ESCAPE オプションを使用しない場合、その後のアンロードされたデータを使用する COPY 操作は失敗する可能性があります。

重要

必ず UNLOAD ステートメントと COPY ステートメントの両方で ESCAPE オプションを使用することを強くお勧めします。ただし、データに区切り文字が含まれていないこと、またはエスケープが必要となる可能性のあるその他の文字が含まれていないことが確実である場合は除きます。

浮動小数点精度の損失

アンロードと再ロードを連続して実行した浮動小数点データは精度を失っていることがあります。

Limit 句

SELECT クエリは、外部の SELECT で LIMIT 句を使用することはできません。たとえば、次の UNLOAD ステートメントは失敗します。


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

代わりに、次の例のようにネストした LIMIT 句を使用してください。


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

SELECT…INTO を使ってテーブルを入力するか、LIMIT 句を使って CREATE TABLE AS を実行し、そのテーブルからアンロードすることもできます。

GEOMETRY データ型の列のアップロード

GEOMETRY 列はテキストまたは CSV 形式でのみアップロードできます。FIXEDWIDTH オプションを使用して、GEOMETRY データをアップロードすることはできません。データは、16 進数の Extended Well-Known Binary (EWKB) 形式でアップロードされます。EWKB データのサイズが 4 MB 以上の場合、後でテーブルにデータをロードできなくなるため、警告が表示されます。

HLLSKETCH データ型のアンロード

HLLSKETCH 列はテキストまたは CSV 形式でのみアンロードできます。FIXEDWIDTH オプションを使用して、HLLSKETCH データをアップロードすることはできません。データは、デンスの HyperLogLog スケッチの場合は Base64 形式、スパースの HyperLogLog スケッチの場合は JSON 形式でアンロードされます。詳細については、「」を参照してくださいHyperLogLog 関数

次の例では、HLLSKETCH 列を含むテーブルをファイルにエクスポートします。


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;

FORMAT AS PARQUET 句

FORMAT AS PARQUET を使用する場合は、次の考慮事項に注意してください。

[Unload to Parquet (Parquet にアンロード)] では、ファイルレベルの圧縮は使用されません。各行グループは SNAPPY で圧縮されます。
MAXFILESIZE を指定しない場合、デフォルトの最大ファイルサイズは 6.2 GB です。MAXFILESIZE を使用して、5 MB～6.2 GB のファイルサイズを指定できます。実際のファイルサイズは、ファイルの書き込み時に概算されるため、指定した数と正確に等しくない場合があります。

スキャンパフォーマンスを最大化するため、Amazon Redshift はまったく同じサイズの 32 MB の行グループを含む Parquet ファイルの作成を試みます。指定した MAXFILESIZE 値は、32 MB の最も近い倍数に自動的に切り捨てられます。たとえば、MAXFILESIZE 200 MB を指定すると、アンロードされた各 Parquet ファイルは約 192 MB になります (32 MB の行グループ x 6 = 192 MB)。
列で TIMESTAMPTZ データ形式が使用されている場合、タイムスタンプ値のみがアンロードされます。タイムゾーン情報はアンロードされません。
アンダースコア (_) 文字またはピリオド (.) 文字で始まるファイル名プレフィックスを指定しないでください。Redshift Spectrum は、これらの文字で始まるファイルを隠しファイルとして処理し、無視します。

PARTITION BY 句

PARTITION BY を使用する場合は、次の考慮事項に注意してください。

パーティション列は出力ファイルに含まれていません。
必ず、UNLOAD ステートメントで使用される SELECT クエリにパーティション列を含めてください。UNLOAD コマンドでは、任意の数のパーティション列を指定できます。ただし、ファイルの一部となる非パーティション列が少なくとも 1 つ存在する必要があるという制限があります。
パーティションキー値が null の場合、Amazon Redshift はそのデータをデフォルトパーティション (partition_column=__HIVE_DEFAULT_PARTITION__) に自動的にアンロードします。
UNLOAD コマンドでは、外部カタログへの呼び出しは行われません。新しいパーティションを既存の外部テーブルの一部として登録するには、別個の ALTER TABLE ... ADD PARTITION ... コマンドを使用します。または、CREATE EXTERNAL TABLE コマンドを実行して、アンロードされたデータを新しい外部テーブルとして登録することもできます。また、AWS Glue クローラを使用して、データカタログにデータを入力することもできます。詳細については、AWS Glue デベロッパーガイドのクローラの定義を参照してください。
MANIFEST オプションを使用する場合、Amazon Redshift はルート Amazon S3 フォルダにマニフェストファイルを 1 つだけ生成します。
パーティションキーとして使用できる列のデータ型は、SMALLINT、INTEGER、BIGINT、DECIMAL、REAL、BOOLEAN、CHAR、VARCHAR、DATE および TIMESTAMP です。

ASSUMEROLE 権限を使用して、UNLOAD オペレーションの IAM ロールへのアクセスを許可する

特定のユーザーおよびグループに UNLOAD オペレーション用の IAM ロールへのアクセスを提供するために、スーパーユーザーは IAM ロールに対する ASSUMEROLE 権限をユーザーおよびグループに付与できます。詳細については、GRANT を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

TRUNCATE

UNLOAD の例