如需與 Amazon Timestream for LiveAnalytics 類似的功能，請考慮使用 Amazon Timestream for InfluxDB。它提供簡化的資料擷取和單一位數毫秒查詢回應時間，以進行即時分析。[在這裡](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html)進一步了解。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # UNLOAD 概念 ## 語法 ``` UNLOAD (SELECT statement) TO 's3://bucket-name/folder' WITH ( option = expression [, ...] ) ``` 其中 `option`是 ``` { partitioned_by = ARRAY[ col_name[,…] ] | format = [ '{ CSV | PARQUET }' ] | compression = [ '{ GZIP | NONE }' ] | encryption = [ '{ SSE_KMS | SSE_S3 }' ] | kms_key = '' | field_delimiter ='' | escaped_by = '' | include_header = ['{true, false}'] | max_file_size = '' | } ``` ## Parameters SELECT 陳述式 用於從一或多個 Timestream for LiveAnalytics 資料表選取和擷取資料的查詢陳述式。 ``` (SELECT column 1, column 2, column 3 from database.table where measure_name = "ABC" and timestamp between ago (1d) and now() ) ``` TO 子句 ``` TO 's3://bucket-name/folder' ``` 或 ``` TO 's3://access-point-alias/folder' ``` `UNLOAD` 陳述式中的 `TO`子句指定查詢結果輸出的目的地。您需要提供完整路徑，包括 Amazon S3 儲存貯體名稱或具有 Amazon S3 上資料夾位置的 Amazon S3 access-point-alias，其中 Timestream for LiveAnalytics 會寫入輸出檔案物件。S3 儲存貯體應該由同一帳戶和同一區域擁有。除了查詢結果集之外，Timestream for LiveAnalytics 還會將資訊清單和中繼資料檔案寫入指定的目的地資料夾。 PARTITIONED\_BY 子句 ``` partitioned_by = ARRAY [col_name[,…] , (default: none) ``` `partitioned_by` 子句用於查詢中，以精細層級分組和分析資料。當您將查詢結果匯出至 S3 儲存貯體時，您可以選擇根據選取查詢中的一或多個資料欄來分割資料。分割資料時，匯出的資料會根據分割區資料欄分割為子集，而每個子集會存放在個別的資料夾中。在包含匯出資料的結果資料夾中，`folder/results/partition column = partition value/`會自動建立子資料夾。不過，請注意，分割的資料欄不包含在輸出檔案中。 `partitioned_by` 不是語法中的強制性子句。如果您選擇在沒有分割的情況下匯出資料，則可以在語法中排除 子句。 **Example** 假設您正在監控網站的點擊串流資料，並擁有 5 個流量通道，即 `direct`、`Social Media`、`Other`、 `Organic Search`和 `Referral`。匯出資料時，您可以選擇使用資料欄 分割資料`Channel`。在您的資料資料夾 中`s3://bucketname/results`，您會有五個資料夾，每個資料夾都有各自的頻道名稱，例如，`s3://bucketname/results/channel=Social Media/.`在此資料夾中，您會透過`Social Media`頻道找到所有登陸您網站之客戶的資料。同樣地，您還有其他資料夾可供其餘頻道使用。 依頻道資料欄分割的匯出資料 ![](http://docs.aws.amazon.com/zh_tw/timestream/latest/developerguide/images/unload-results.png) FORMAT ``` format = [ '{ CSV | PARQUET }' , default: CSV ``` 用於指定寫入 S3 儲存貯體之查詢結果格式的關鍵字。您可以使用逗號 (，) 做為預設分隔符號，或 Apache Parquet 格式的有效開放單欄式儲存格式，將資料匯出為逗號分隔值 (CSV)。 壓縮 ``` compression = [ '{ GZIP | NONE }' ], default: GZIP ``` 您可以使用壓縮演算法 GZIP 壓縮匯出的資料，或指定 `NONE`選項將其解壓縮。 ENCRYPTION ``` encryption = [ '{ SSE_KMS | SSE_S3 }' ], default: SSE_S3 ``` Amazon S3 上的輸出檔案會使用您選取的加密選項進行加密。除了您的資料之外，資訊清單和中繼資料檔案也會根據您選取的加密選項進行加密。我們目前支援 SSE\_S3 和 SSE\_KMS 加密。SSE\_S3 是一種伺服器端加密，Amazon S3 會使用 256 位元進階加密標準 (AES) 加密來加密資料。SSE\_KMS 是一種伺服器端加密，可使用客戶受管金鑰加密資料。 KMS\_KEY ``` kms_key = '' ``` KMS 金鑰是客戶定義的金鑰，用於加密匯出的查詢結果。KMS Key 由 AWS Key Management Service (AWS KMS) 安全管理，並用於加密 Amazon S3 上的資料檔案。 FIELD\_DELIMITER ``` field_delimiter ='' , default: (,) ``` 以 CSV 格式匯出資料時，此欄位會指定單一 ASCII 字元，用於分隔輸出檔案中的欄位，例如管道字元 (\|)、逗號 (，) 或標籤 (/t)。CSV 檔的預設分隔符號為逗號字元。如果資料中的值包含選擇的分隔符號，則會以引號字元引用分隔符號。例如，如果您資料中的 值包含 `Time,stream`，則會在匯出的資料`"Time,stream"`中引用此值。Timestream for LiveAnalytics 使用的引號字元是雙引號 (")。 `FIELD_DELIMITER` 如果您想要在 CSV 中包含標頭，請避免指定換行字元 (ASCII 13、十六進位 `0D`、文字 '\\r') 或換行字元 (ASCII 10、十六進位 0A、文字 '\\n') 做為 ，因為這會阻止許多剖析器在產生的 CSV 輸出中正確剖析標頭。 ESCAPED\_BY ``` escaped_by = '', default: (\) ``` 以 CSV 格式匯出資料時，此欄位會指定在寫入 S3 儲存貯體的資料檔案中應視為逸出字元的字元。逸出發生在下列案例中： 1. 如果值本身包含引號字元 (")，則會使用逸出字元逸出。例如，如果值為 `Time"stream`，其中 (\\) 是設定的逸出字元，則會將其逸出為 `Time\"stream`。 1. 如果值包含設定的逸出字元，則會逸出。例如，如果值為 `Time\stream`，則會以 逸出`Time\\stream`。 如果匯出的輸出在類似陣列、資料列或時間序列中包含複雜的資料類型，則會序列化為 JSON 字串。以下是範例。 [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/timestream/latest/developerguide/export-unload-concepts.html) INCLUDE\_HEADER ``` include_header = 'true' , default: 'false' ``` 以 CSV 格式匯出資料時，此欄位可讓您將資料欄名稱包含為匯出 CSV 資料檔案的第一列。 接受的值為「true」和「false」，預設值為「false」。文字轉換選項，例如 `escaped_by`和 也`field_delimiter`適用於標頭。 包含標頭時，請務必不要選取換行字元 (ASCII 13、十六進位 0D、文字 '\\r') 或換行字元 (ASCII 10、十六進位 0A、文字 '\\n') 做為 `FIELD_DELIMITER`，因為這會阻止許多剖析器在產生的 CSV 輸出中正確剖析標頭。 MAX\_FILE\_SIZE ``` max_file_size = 'X[MB|GB]' , default: '78GB' ``` 此欄位指定`UNLOAD`陳述式在 Amazon S3 中建立的檔案大小上限。`UNLOAD` 陳述式可以建立多個檔案，但寫入 Amazon S3 的每個檔案的大小上限大約是此欄位中指定的大小。 欄位的值必須介於 16 MB 到 78 GB 之間。您可以指定整數，例如 `12GB`，或小數，例如 `0.5GB`或 `24.7MB`。預設值為 78 GB。 實際檔案大小會在寫入檔案時近似，因此實際大小上限可能不完全等於您指定的數字。 ## 寫入 S3 儲存貯體的內容為何？ 對於每個成功執行的 UNLOAD 查詢，Timestream for LiveAnalytics 會將您的查詢結果、中繼資料檔案和資訊清單檔案寫入 S3 儲存貯體。如果您已分割資料，則結果資料夾中會有所有分割區資料夾。資訊清單檔案包含 UNLOAD 命令所寫入的檔案清單。中繼資料檔案包含描述寫入資料之特性、屬性和屬性的資訊。 ## 匯出的檔案名稱是什麼？ 匯出的檔案名稱包含兩個元件，第一個元件是 queryID，第二個元件是唯一的識別符。 CSV 檔案 ``` S3://bucket_name/results/_.csv S3://bucket_name/results/=/_.csv ``` 壓縮的 CSV 檔案 ``` S3://bucket_name/results/=/_.gz ``` Parquet 檔案 ``` S3://bucket_name/results/=/_.parquet ``` 中繼資料和資訊清單檔案 ``` S3://bucket_name/__manifest.json S3://bucket_name/__metadata.json ``` 由於 CSV 格式的資料存放在檔案層級，當您在匯出至 S3 時壓縮資料時，檔案會有「.gz」副檔名。不過，Parquet 中的資料會在資料欄層級壓縮，因此即使您在匯出時壓縮資料，檔案仍會有 .parquet 副檔名。 ## 每個檔案包含哪些資訊？ ### 清單檔案 資訊清單檔案提供使用 UNLOAD 執行匯出的檔案清單資訊。清單檔案可在提供的 S3 儲存貯體中使用，檔案名稱為：`s3:///__manifest.json`。資訊清單檔案將包含結果資料夾中檔案的 URL、個別檔案的記錄數和大小，以及查詢中繼資料 （這是匯出至 S3 的查詢總位元組數和總列數）。 ``` { "result_files": [ { "url":"s3://my_timestream_unloads/ec2_metrics/AEDAGANLHLBH4OLISD3CVOZZRWPX5GV2XCXRBKCVD554N6GWPWWXBP7LSG74V2Q_1448466917_szCL4YgVYzGXj2lS.gz", "file_metadata": { "content_length_in_bytes": 32295, "row_count": 10 } }, { "url":"s3://my_timestream_unloads/ec2_metrics/AEDAGANLHLBH4OLISD3CVOZZRWPX5GV2XCXRBKCVD554N6GWPWWXBP7LSG74V2Q_1448466917_szCL4YgVYzGXj2lS.gz", "file_metadata": { "content_length_in_bytes": 62295, "row_count": 20 } }, ], "query_metadata": { "content_length_in_bytes": 94590, "total_row_count": 30, "result_format": "CSV", "result_version": "Amazon Timestream version 1.0.0" }, "author": { "name": "Amazon Timestream", "manifest_file_version": "1.0" } } ``` ### 中繼資料 中繼資料檔案提供有關資料集的其他資訊，例如資料欄名稱、資料欄類型和結構描述。中繼資料檔案可在提供的 S3 儲存貯體中使用，檔案名稱為：S3：//bucket\_name/\_\_metadata.json 以下是中繼資料檔案的範例。 ``` { "ColumnInfo": [ { "Name": "hostname", "Type": { "ScalarType": "VARCHAR" } }, { "Name": "region", "Type": { "ScalarType": "VARCHAR" } }, { "Name": "measure_name", "Type": { "ScalarType": "VARCHAR" } }, { "Name": "cpu_utilization", "Type": { "TimeSeriesMeasureValueColumnInfo": { "Type": { "ScalarType": "DOUBLE" } } } } ], "Author": { "Name": "Amazon Timestream", "MetadataFileVersion": "1.0" } } ``` 在中繼資料檔案中共用的資料欄資訊與`SELECT`查詢的查詢 API 回應中`ColumnInfo`傳送的結構相同。 ### 結果 結果資料夾包含以 Apache Parquet 或 CSV 格式匯出的資料。 ## 範例 當您透過`UNLOAD`查詢 API 提交如下所示的查詢時， ``` UNLOAD(SELECT user_id, ip_address, event, session_id, measure_name, time, query, quantity, product_id, channel FROM sample_clickstream.sample_shopping WHERE time BETWEEN ago(2d) AND now()) TO 's3://my_timestream_unloads/withoutpartition/' WITH ( format='CSV', compression='GZIP') ``` `UNLOAD` 查詢回應將有 1 列 \* 3 欄。這 3 個資料欄為： + BIGINT 類型的資料列 - 指出匯出的資料列數 + metadataFile 類型 VARCHAR - 即匯出的中繼資料檔案的 S3 URI + manifestFile 類型 VARCHAR - 這是匯出的資訊清單檔案的 S3 URI 您將會從查詢 API 收到下列回應： ``` { "Rows": [ { "Data": [ { "ScalarValue": "20" # No of rows in output across all files }, { "ScalarValue": "s3://my_timestream_unloads/withoutpartition/AEDAAANGH3D7FYHOBQGQQMEAISCJ45B42OWWJMOT4N6RRJICZUA7R25VYVOHJIY__metadata.json" #Metadata file }, { "ScalarValue": "s3://my_timestream_unloads/withoutpartition/AEDAAANGH3D7FYHOBQGQQMEAISCJ45B42OWWJMOT4N6RRJICZUA7R25VYVOHJIY__manifest.json" #Manifest file } ] } ], "ColumnInfo": [ { "Name": "rows", "Type": { "ScalarType": "BIGINT" } }, { "Name": "metadataFile", "Type": { "ScalarType": "VARCHAR" } }, { "Name": "manifestFile", "Type": { "ScalarType": "VARCHAR" } } ], "QueryId": "AEDAAANGH3D7FYHOBQGQQMEAISCJ45B42OWWJMOT4N6RRJICZUA7R25VYVOHJIY", "QueryStatus": { "ProgressPercentage": 100.0, "CumulativeBytesScanned": 1000, "CumulativeBytesMetered": 10000000 } } ``` ## 資料類型 `UNLOAD` 陳述式支援 中所述的所有 Timestream for LiveAnalytics 查詢語言資料類型，但 `time`和 [支援的資料類型](supported-data-types.md)除外`unknown`。