コンソールにサインインする
Amazon Redshift
データベース開発者ガイド (API バージョン 2012-12-01)

AWS ドキュメント » Amazon Redshift » データベース開発者ガイド » SQL リファレンス » SQL コマンド » UNLOAD

UNLOAD

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

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

構文

UNLOAD ('select-statement')
TO 's3://object-path/name-prefix'
authorization
[ option [ ... ] ]

where option is

{ MANIFEST [ VERBOSE ] 
| HEADER

            
| [ FORMAT [AS] ] CSV
| DELIMITER [ AS ] 'delimiter-char' 
| FIXEDWIDTH [ AS ] 'fixedwidth-spec' }  
| ENCRYPTED
| 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'

パラメータ

('select-statement')

SELECT クエリ。クエリ結果をアンロードします。ほとんどの場合、クエリで ORDER BY 句を指定してソート順にデータをアンロードすることは有益です。この方法は、データの再ロード時にデータをソートするために必要な時間を節約します。TOP は SELECT 句ではサポートされていません。代わりに LIMIT を使用してください。

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

('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 というプレフィックスが付きます。さらにセキュリティを強化するために、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 コマンドの構文リファレンスの「認証パラメータ」を参照してください。

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 は併用できません。

[ FORMAT [AS] ] CSV

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

キーワード FORMAT および AS はオプションです。CSV と DELIMITER または FIXEDWIDTH を併用することはできません。

DELIMITER AS 'delimiter_character'

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

FIXEDWIDTH 'fixedwidth_spec'

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

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

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

ENCRYPTED

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

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

お客様が用意した対称キーによるクライアント側の暗号化 (CSE-CMK) を使用して Amazon S3 にアンロードするには、MASTER_SYMMETRIC_KEY パラメータ、または CREDENTIALS 認証文字列の master_symmetric_key 部分を使用して、キーを指定します。マスター対称キーを使用してデータをアンロードする場合は、暗号化済みデータを COPY する場合と同じキーを指定する必要があります。

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

暗号化されたアンロードファイルを圧縮するには、BZIP2、GZIP または ZSTD パラメータを追加します。

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 および 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 文字列の幅より小さい場合、次の動作が発生します。

  • 空のフィールドは非文字列用の出力です。

  • 文字列に対してはエラーがレポートされます。

ESCAPE

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

  • ラインフィード: \n

  • キャリッジリターン: \r

  • アンロードデータ用に指定された区切り文字。

  • エスケープ文字: \

  • 引用符: " または ' (ESCAPE と ADDQUOTES の両方を UNLOAD コマンドで指定した場合)。

重要

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

ALLOWOVERWRITE

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

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 ]

Amazon S3 で作成された UNLOAD ファイルの最大サイズ。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 を実行し、そのテーブルからアンロードすることができます。