Amazon Timestream for LiveAnalytics に類似した機能をご希望の場合は Amazon Timestream for InfluxDB をご検討ください。リアルタイム分析に適した、シンプルなデータインジェストと 1 桁ミリ秒のクエリ応答時間を特徴としています。詳細については、[こちら](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 = '' | } ``` ## パラメータ SELECT ステートメント LiveAnalytics テーブルの 1 つ以上の Timestream からデータを選択および取得するために使用されるクエリステートメント。 ``` (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` 句は、クエリ結果の出力先を指定します。Timestream for LiveAnalytics が出力ファイルオブジェクトを書き込む Amazon S3 上のフォルダの場所を含め、Amazon S3 バケット名または Amazon S3 アクセスポイントエイリアスを含むフルパスを指定する必要があります。S3 バケットは、同じアカウントと同じリージョンで所有されている必要があります。Timestream for LiveAnalytics はクエリ結果セットに加えてマニフェストファイルとメタデータファイルを指定された宛先フォルダに書き込みます。 PARTITIONED\_BY 句 ``` partitioned_by = ARRAY [col_name[,…] , (default: none) ``` `partitioned_by` 句は、データを詳細なレベルでグループ化して分析するためのクエリで使用されます。クエリ結果を S3 バケットにエクスポートする場合、選択クエリの 1 つ以上の列に基づいてデータをパーティショニングすることを選択できます。データをパーティショニングする場合、エクスポートされたデータはパーティション列に基づいてサブセットに分割され、各サブセットは個別のフォルダに保存されます。エクスポートされたデータを含む結果フォルダ内に、サブフォルダ `folder/results/partition column = partition value/` が自動的に作成されます。ただし、パーティショニングされた列は出力ファイルに含まれないことに注意してください。 `partitioned_by` は構文の必須句ではありません。パーティショニングなしでデータをエクスポートする場合は、構文で句を除外できます。 **Example** ウェブサイトのクリックストリームデータをモニタリングしていて、`direct`、`Social Media`、`Organic Search`、`Other`、`Referral` の 5 つのトラフィックチャネルがあるとします。データをエクスポートするときは、列 `Channel` を使用してデータをパーティショニングすることを選択できます。データフォルダ `s3://bucketname/results` 内には、それぞれのチャネル名を持つ 5 つのフォルダがあります。例えば、`s3://bucketname/results/channel=Social Media/.` フォルダ内には、`Social Media` チャネルを介してウェブサイトに到着したすべての顧客のデータがあります。同様に、残りのチャネルには他のフォルダがあります。 Channel 列でパーティショニングされたエクスポートされたデータ ![](http://docs.aws.amazon.com/ja_jp/timestream/latest/developerguide/images/unload-results.png) FORMAT ``` format = [ '{ CSV | PARQUET }' , default: CSV ``` S3 バケットに書き込まれるクエリ結果の形式を指定するキーワード。データは、カンマ (,) をデフォルトの区切り文字として使用してカンマ区切り値 (CSV) として、または分析用の効率的なオープン列型ストレージ形式である Apache Parquet 形式でエクスポートできます。 COMPRESSION ``` compression = [ '{ GZIP | NONE }' ], default: GZIP ``` エクスポートされたデータは、圧縮アルゴリズム GZIP を使用して圧縮することも、`NONE` オプションを指定して解凍することもできます。 ENCRYPTION ``` encryption = [ '{ SSE_KMS | SSE_S3 }' ], default: SSE_S3 ``` Amazon S3 の出力ファイルは、選択した暗号化オプションを使用して暗号化されます。データに加えて、マニフェストおよびメタデータファイルも、選択した暗号化オプションに基づいて暗号化されます。現在、SSE\_S3 および SSE\_KMS 暗号化がサポートされています。SSE\_S3 は、256 ビットの高度暗号化標準 (AES) 暗号化を使用してデータを暗号化する Amazon S3 によるサーバー側の暗号化です。SSE\_KMS は、カスタマーマネージドキーを使用してデータを暗号化するサーバー側の暗号化です。 KMS\_KEY ``` kms_key = '' ``` KMS キーは、エクスポートされたクエリ結果を暗号化するためのユーザー定義のキーです。KMS キーは AWS Key Management Service (AWS KMS) によって安全に管理され、Amazon S3 のデータファイルの暗号化に使用されます。 FIELD\_DELIMITER ``` field_delimiter ='' , default: (,) ``` CSV 形式でデータをエクスポートするとき、このフィールドはパイプ文字 (\|)、カンマ (,)、タブ (\\t) など、出力ファイルのフィールドを区切るために使用する単一の ASCII 文字を指定します。CSV ファイルのデフォルトの区切り文字はコンマ文字です。データの値に選択した区切り文字が含まれている場合、区切り文字は引用符で囲まれます。例えば、データ内の値に `Time,stream` が含まれている場合、この値はエクスポートされたデータで `"Time,stream"` として引用符で囲まれます。Timestream for LiveAnalytics で使用される引用文字は二重引用符 (") です。 CSV にヘッダーを含める場合は、キャリッジリターン文字 (ASCII 13、16 進数 `0D`、テキスト '\\r') または改行文字 (ASCII 10、16 進数 0A、テキスト '\\n') を `FIELD_DELIMITER` として指定しないでください。これにより、多くのパーサーが生成された 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/ja_jp/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、16 進 0D、テキスト '\\r') または改行文字 (ASCII 10、16 進 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 コマンドによって書き込まれたファイルのリストが含まれています。メタデータファイルには、書き込まれたデータの特性、プロパティ、属性を記述する情報が含まれています。 ## エクスポートされたファイル名とは エクスポートされたファイル名には 2 つのコンポーネントが含まれており、最初のコンポーネントは queryID、2 番目のコンポーネントは一意の識別子です。 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:///__manifest.json` の指定された S3 バケットで使用できます。マニフェストファイルには、結果フォルダ内のファイルの 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://bucket\_name/\_\_metadata.json の指定された S3 バケットで使用できます。 メタデータファイルの例を次に示します。 ``` { "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` クエリの Query API レスポンスで送信される `ColumnInfo` と同じ構造です。 ### 結果 結果フォルダには、エクスポートしたデータが Apache Parquet 形式または CSV 形式で格納されます。 ## 例 Query API を使用して次のような `UNLOAD` クエリを送信すると、 ``` 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 行 x 3 列が含まれます。これら 3 つの列は次のとおりです。 + BIGINT 型の行 – エクスポートされた行数 + VARCHAR 型の metadataFile – エクスポートされたメタデータファイルの S3 URI + VARCHAR 型の manifestFile – エクスポートされたマニフェストファイルの S3 URI Query 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` ステートメントは、`time` および `unknown` を除く「[サポートされているデータ型](supported-data-types.md)」で説明されている Timestream for LiveAnalytics クエリ言語のデータ型すべてをサポートします。