UNLOAD - Amazon Redshift

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

UNLOAD

使用 Amazon S3 伺服器端加密 (SSE-S3) 將查詢的結果卸載至 Amazon S3 上的一個或多個文字檔,或 Apache Parquet 檔案。您還可以使用AWS Key Management Service密鑰 (SSE-KMS) 或客户端加密。

默認情況下,卸載文件的格式是管道分隔的(|)。

您可以設定 MAXFILESIZE 參數來管理 Amazon S3 上檔案的大小,以及藉由副檔名管理檔案數目。

您可以將 Amazon Redshift 查詢的結果卸載至 Apache Parquet 中的 Amazon S3 資料湖,這是一種用於分析的高效率開放欄式儲存格式。相較於文字格式,Parquet 格式的卸載速度提升達 2 倍,Amazon S3 中儲存空間減少達 6 倍。這可以讓您將已在 Amazon S3 中執行的資料轉換和資料充實,以開放的格式儲存到 Amazon S3 資料湖。您可以使用 Redshift Spectrum 和其他AWS服務,如 Amazon Athena、亞馬遜 EMR 和 SageMaker。

Syntax (語法)

UNLOAD ('select-statement') TO 's3://object-path/name-prefix' authorization [ option [ ... ] ] where option is { [ FORMAT [ AS ] ] CSV | PARQUET | JSON | 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 ] | ROWGROUPSIZE [AS] size [ MB | GB ] | REGION [AS] 'aws-region' } | IAM_ROLE { default | 'arn:aws:iam::<AWS 帳戶-id>:role/<role-name>' }

參數

('select-statement')

SELECT 查詢。查詢的結果會卸載。大多數情況下,藉由在查詢中指定 ORDER BY 子句依排序順序卸載資料會有其實用性。此方式可節省重新載入資料時,排序資料所需的時間。

查詢必須用單引號括住,如下所示:

('select * from venue order by venueid')
注意

如果查詢包含引號 (例如為了將常值括住),請將常值放在兩組單引號內-您也必須將查詢在含括在單引號內:

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

Amazon Redshift 在 Amazon S3 上寫入輸出檔案物件之位置的完整路徑 (包括儲存貯體名稱在內),若指定了 MANIFEST,則包括資訊清單檔案。物件名稱前面會加上 name-prefix。如果您使用 PARTITION BY,會自動視需要將一個斜線 (/) 新增到 name-prefix 值的結尾。為了提升安全性,UNLOAD 會使用 HTTPS 連線連接至 Amazon S3。根據預設,UNLOAD 會在每個分割中寫入一個或多個檔案。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 選項。

重要

當 Amazon S3 儲存儲體不在相同AWS區域為 Amazon Redshift 叢集。

Authorization

UNLOAD 命令需要授權才能將資料寫入 Amazon S3。UNLOAD 命令會使用與 COPY 命令相同的參數進行授權。如需詳細資訊,請參閱 COPY 命令語法參考中的 授權參數

[格式 [作為] CSV | 實木複合地板 | JSON

關鍵字,用於指定要覆蓋默認格式的卸載格式。

使用 CSV 時,會使用逗號 ( , ) 字元做為預設分隔符號卸載至 CSV 格式的文字檔案。如果欄位包含分隔符號、雙引號、新行字元或歸位字元,已卸載檔案中的欄位便會括在雙引號中。資料欄位中的雙引號會使用額外的雙引號進行逸出。

使用 PARQUET 時,會卸載至 Apache Parquet 1.0 版格式的檔案。根據預設,每個資料列群組都會使用 SNAPPY 壓縮進行壓縮。如需 Apache Parquet 格式的詳細資訊,請參閱 Parquet

當 JSON 時,卸載到 JSON 文件,其中每行都包含一個 JSON 對象,表示查詢結果中的完整記錄。當查詢結果包含超級列時,Redshift 支持寫入嵌套 JSON。要創建有效的 JSON 對象,查詢中每個列的名稱必須唯一。在 JSON 文件中,布爾值被卸載為t或者f,NULL 值被卸載為null

FORMAT 和 AS 關鍵字是選用的。您無法使用 CSV 與 FIXEDWIDTH 搭配。您無法搭配 DELIMITER、FIXEDWIDTH、ADDQUOTES、ESCAPE、NULL AS、HEADER、GZIP、BZIP2 或 ZSTD 使用 PARQUET。搭配 ENCRYPTED 的 PARQUET 僅支援使用 AWS Key Management Service 金鑰 (SSE-KMS) 進行的伺服器端加密。您無法搭配 JSON 搭配 DELIMITES,標題,FIXEDWIDTH,ADDQUOTES,或 NULL AS 使用 JSON。

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

指定卸載操作的分割區索引鍵。UNLOAD 會依序根據分割區索引鍵的值和 Apache Hive 慣例,自動將輸出檔案分到分割資料夾。例如,屬於 2019 年分割區和九月分割區的 Parquet 檔案便會具有以下字首:s3://my_bucket_name/my_prefix/year=2019/month=September/000.parquet

column_name 的值必須是正在卸載查詢結果中的資料行。

如果您指定 PARTITION BY 搭配 INCLUDE 選項,則不會從上傳的檔案中移除分割區資料欄。

Amazon Redshift 不支援 PARTION BY 子句中的字符串文字。

MANIFEST [ VERBOSE ]

會建立資訊清單檔案,當中明確列出 UNLOAD 程序建立的資料檔案的詳細資訊。資訊清單是 JSON 格式的文字檔,其中列出寫入 Amazon S3 的每個檔案的 URL。

如果指定 MANIFEST 時搭配 VERBOSE 選項,則資訊清單會包含下列詳細資訊:

  • 資料欄名稱和資料類型,以及針對 CHAR、VARCHAR 或 NUMERIC 資料類型,每個資料欄的維度。針對 CHAR 和 VARCHAR 資料類型,維度為長度。針對 DECIMAL 或 NUMERIC 資料類型,維度為精確度和規模。

  • 卸載至每個檔案的資料列計數。如果指定了 HEADER 選項,則資料列計數會包括標題行。

  • 卸載的所有檔案的檔案大小總計以及卸載至所有檔案的資料列計數總計。如果指定了 HEADER 選項,則資料列計數會包括標題行。

  • 作者。作者一律是 "Amazon Redshift"。

您只能在 MANIFEST 之後指定 VERBOSE。

資訊清單檔案會寫入和卸載檔案相同的 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'

指定單一 ASCII 字元,用以分隔輸出檔案中的欄位,例如縱線字元 ( | )、逗號 ( , ) 或 Tab 字元 ( \t )。文字檔的預設分隔符號為縱線字元。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 會自動建立加密檔案,使用 Amazon S3 伺服器端加密搭配AWS受管理的加密金鑰 (SSE-S3)。

對於 ENCRIPTED,您可能希望使 Amazon S3 伺服器端加密搭配AWS KMS金鑰 (SSE-KMS)。如果是這種情況,請使用 KMS_KEY_ID 參數來提供金鑰 ID。您無法使用 CREDENTIALS 參數搭配 KMS_KEY_ID 參數。如果您使用 KMS_KEY_ID 針對資料執行 UNLOAD 命令,您接著便可以針對相同的資料執行 COPY 操作,而無須指定金鑰。

若要使用用用户端加密搭配客户提供的對稱金鑰卸載至 Amazon S3,請以下列兩種方式之一提供金鑰。如要提供金鑰,請使用 MASTER_SYMMETRIC_KEY 參數,或是 CREDENTIALS 登入資料字串的 master_symmetric_key 部分。如果您使用根對稱密鑰卸載資料,請務必在針對加密資料執行 COPY 操作時提供相同的密鑰。

UNLOAD 不支援 Amazon S3 伺服器端加密搭配客户提供的密鑰 (SSE-C)。

如果使用加密自動,則卸載命令將獲取默認AWS KMS加密密鑰,並 Amazon S3 用AWS KMS金鑰。如果存儲桶沒有默認AWS KMS加密鑰,UNLOAD 會使用 Amazon Redshift 伺服器端加密和AWS受管理的加密金鑰 (SSE-S3)。您無法搭配 KMS_KEY_ID、MASTER_SYMMETRIC_KEY 或包含 master_symmetric_key 的 CREDENTIALS 使用此選項。

KMS_KEY_ID 'key-id'

指定AWS Key Management Service(AWS KMS) 金鑰,用來加密 Amazon S3 上的資料檔案。如需詳細資訊,請參閱什麼是 AWS Key Management Service? 如果您指定 KMS_KEY_ID,則必須一併指定 ENCRYPTED 參數。如果您指定 KMS_KEY_ID,則不能使用 CREDENTIALS 參數進行驗證。請改用 IAM_ROLEACCESS_KEY_ID and SECRET_ACCESS_KEY

主對稱密鑰 '根鍵'

指定要用來加密 Amazon S3 上資料檔案的根對稱金鑰。如果您指定 MASTER_SYMMETRIC_KEY,則必須一併指定 ENCRYPTED 參數。您無法使用 MASTER_SYMMETRIC_KEY 與 CREDENTIALS 參數搭配。如需詳細資訊,請參閱 從 Amazon S3 載入加密的資料檔案

BZIP2

將資料卸載至每個分割中的一個或多個 bzip2 壓縮檔。產生的每個檔案都會附加 .bz2 副檔名。

GZIP

將資料卸載至每個分割中的一個或多個 gzip 壓縮檔。產生的每個檔案都會附加 .gz 副檔名。

ZSTD

將資料卸載至每個分割中的一個或多個 Zstandard 壓縮檔。產生的每個檔案都會附加 .zst 副檔名。

ADDQUOTES

在每個卸載的資料欄位前後加上引號,以卸載包含分隔符號本身的資料值。例如,如果分隔符號是逗號,您可以成功卸載並重新載入下列資料:

"1","Hello, World"

如果沒有新增雙引號,Hello, World 字串將會剖析為兩個不同欄位。

若您使用 ADDQUOTES,則必須在重新載入資料時,於 COPY 中指定 REMOVEQUOTES。

NULL AS 'null-string'

指定一個字串,代表卸載檔案中的 null 值。若使用此選項,所有輸出檔案都會包含指定的字串,用以取代所選取資料中找到的任何 null 值。若未指定此選項,則 null 值會卸載為:

  • 分隔符號輸出的零長度字串

  • 固定寬度輸出的空白字串

若針對固定寬度卸載指定 null 字串,而輸出資料欄的寬度小於 null 字串的寬度,則會發生下列行為:

  • 非字元資料欄的輸出為空欄位

  • 針對字元資料欄回報錯誤

與用户定義的字符串表示空值的其他數據類型不同,Amazon Redshift 使用 JSON 格式導出 SUPER 數據列,並將其表示為空值(由 JSON 格式確定)。因此,超級數據列會忽略卸載命令中使用的 NULL [AS] 選項。

ESCAPE

分隔符號卸載檔案的 CHAR 和 VARCHAR 資料欄中會放入逸出字元 (\),位於出現下列字元的每個位置前面:

  • 換行:\n

  • 歸位字元: \r

  • 針對卸載資料指定的分隔符號字元。

  • 逸出字元:\

  • 引號字元:"' (如果 UNLOAD 命令中同時指定了 ESCAPE 與 ADDQUOTES)。

重要

如果您使用 COPY 搭配 ESCAPE 選項載入資料,則在 UNLOAD 命令中也必須指定 ESCAPE 選項,以產生具相互關係的輸出檔案。同樣地,如果您使用 ESCAPE 選項執行 UNLOAD,則在 COPY 相同的資料時需要使用 ESCAPE。

ALLOWOVERWRITE

根據預設,若找到可能會覆寫的檔案,則 UNLOAD 會失敗。若指定了 ALLOWOVERWRITE,UNLOAD 會覆寫現有檔案,包括資訊清單檔案。

清潔路徑

在將文件卸載到指定位置之前,CLEANPATH 選項會刪除位於 TO 子句中指定的 Amazon S3 路徑中的現有文件。

如果包括 PARTION BY 子句,則僅從分區文件夾中刪除現有文件,以接收 UNLOAD 操作生成的新文件。

您必須有s3:DeleteObjectAmazon S3 儲存貯體的權限。如需相關資訊,請參閱「」。Amazon S3 中的政策和許可中的Amazon Simple Storage Service 使用指南。您使用 CLEANPATH 選項刪除的檔案會永久刪除,且無法復原。

如果您指定允許覆蓋選項,則不能指定清理路徑選項。

PARALLEL

依預設,UNLOAD 會根據叢集中的分割數,將資料平行寫入多個檔案。預設選項為 ON 或 TRUE。若 PARALLEL 為 OFF 或 FALSE,則 UNLOAD 會依序寫入一個或多個資料檔案,並絕對會根據 ORDER BY 子句 (如有使用的話) 排序。資料檔案大小上限為 6.2 GB。因此,假如您卸載 13.4 GB 的資料,UNLOAD 會建立下列三個檔案。

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

UNLOAD 命令是設計為使用平行處理。我們建議在多數的情況將 PARALLEL 保持為啟用,特別是在使用 COPY 命令將檔案是用來載入表格時。

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

指定 UNLOAD 在 Amazon S3 中建立的檔案大小上限。指定介於 5 MB 和 6.2 GB 之間的小數值。AS 關鍵字為選用。預設單位為 MB。如果未指定 MAXFILESIZE,則預設的檔案大小上限為 6.2 GB。資訊清單檔案的大小 (如有使用的話) 不受 MAXFILESIZE 的影響。

行組大小 [AAS] 大小 [MB | GB]

指定行組的大小。選擇較大的大小可以減少行組的數量,從而減少網絡通信量。指定一個介於 32 MB 和 128 MB 之間的整數值。AS 關鍵字為選用。預設單位為 MB。

如果未指定行組大小,則預設大小是 32 MB。若要使用此參數,存儲格式必須為 Parquet,節點類型必須是 ra3.4xlarge、ra3.16xlarge、ra3.16xlarge、ds2.8xlarge 或 dc2.8xlarge。

REGION [AS] 'aws-region'

指定AWS目標 Amazon S3 儲存儲體所在的區域。UNLOAD 到不在相同之中的 Amazon S3 儲存儲體時,就需要 REGIONAWS區域為 Amazon Redshift 叢集。

的值aws_region必須匹配AWS中列出的區域Amazon Redshift 區域和端點中的AWS一般參考

UNLOAD 會假設目標 Amazon S3 儲存儲體位於相同AWS區域為 Amazon Redshift 叢集。

IAM_ROLE{ 預設 | 'arn: aws: aws: iam።<AWS 帳戶-id >: 角色/<role-name>'

使用默認關鍵字讓 Amazon Redshift 使用 IAM 角色,該角色設置為默認角色,並在運行 UNLOAD 命令時與集羣關聯。

為叢集進行身份驗證和授權時所使用之 IAM 角色使用之 Amazon Resource Name (ARN)。如果指定 IAM_ROLE,則不能使用 ACCESS_KEY_ID 和 SECRET_ACCESS_KEY、SESSION_TOKEN 或 CREDENTIALS。

使用須知

針對所有分隔文字的 UNLOAD 操作使用 ESCAPE

當您使用分隔符號執行 UNLOAD,則您的資料中可能包括分隔符號或 ESCAPE 選項說明中列出的任何字元。在這種情況下,則您必須在 UNLOAD 陳述式中使用 ESCAPE 選項。若您未使用 ESCAPE 選項搭配 UNLOAD,則後續使用卸載資料的 COPY 操作可能會失敗。

重要

強烈建議您一律使用 ESCAPE 搭配 UNLOAD 和 COPY 陳述式。如果您確定資料未包含任何分隔符號或可能需要逸出的其他字元,則為例外。

浮點數精確度喪失

您可能遇到後續卸載並重新載入的浮點資料精確度喪失的情況。

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 資料。資料會以擴充已知二進位 (EWKB) 格式的十六進位形式卸載。如果 EWKB 資料的大小超過 4 MB,則會發生警告,因為資料稍後將無法載入資料表。

卸載 HLLSKETCH 數據類型

您只能將 HLLLSETCH 資料行卸載至文字或 CSV 格式。您無法卸載 HLLSETCH 資料與FIXEDWIDTH選項。數據以 Base64 格式卸載,用於密集 HyperLogLog 草圖或以 JSON 格式為稀疏 HyperLogLog 草圖。如需詳細資訊,請參閱 HyperLogLog LOG 函數

以下示例將包含 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;

卸載 VARBYTY 資料類型的資料欄

您只能將 VARBYTYTY 資料欄卸載至文字或 CSV 格式。資料會以十六進位形式卸載。您無法卸載 VARBYTY 資料與FIXEDWIDTH選項。所以此ADDQUOTES選項的卸載到 CSV 不受支持。VARBYTE 列不能是分區依據列。

FORMAT AS PARQUET 子句

使用 FORMAT AS 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 命令中指定任何數量的分割區資料行。但是,其中一個限制是檔案內至少應包含一個非分割區資料行。

  • 如果分割區索引鍵的值為 Null,Amazon Redshift 會自動將該資料卸載至稱為partition_column=__HIVE_DEFAULT_PARTITION__

  • UNLOAD 命令不會對外部目錄進行任何呼叫。如要註冊您新的分割區,使其成為您現有外部資料表的一部分,請使用單獨的 ALTER TABLE … ADD PARTITION … 命令。或者,您可以執行 CREATE EXTERNAL TABLE 命令來將已卸載的資料註冊為新的外部資料表。您也可以使用AWS Glue填充您的資料目錄。如需詳細資訊,請參閱《AWS Glue 開發人員指南》中的定義編目程式

  • 如果您使用資訊清單選項,Amazon Redshift 會在 Amazon S3 根資料夾中只會產生一個資訊清單檔案。

  • 您可以用來做為分割區索引鍵的資料欄資料類型為 SMALLINT、INTEGER、BIGINT、DECIMAL、REAL、BOOLEAN、CHAR、VARCHAR、DATE 和 TIMESTAMP。

使用 ASUMEROLE 權限授予對 IAM 角色進行卸載操作的訪問權限

要為特定用户和組提供對 IAM 角色進行卸載操作的訪問權限,超級用户可以將 IAM 角色的 ASUMEROLE 權限授予用户和組。如需相關資訊,請參閱 GRANT

卸載不支持 Amazon S3 存取點別名

您不能將 Amazon S3 接入點別名與 UNLOAD 命令一起使用。