Amazon Timestream for LiveAnalytics に類似した機能をご希望の場合は Amazon Timestream for InfluxDB をご検討ください。リアルタイム分析に適した、シンプルなデータインジェストと 1 桁ミリ秒のクエリ応答時間を特徴としています。詳細については、[こちら](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html)を参照してください。 翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # UNLOAD を使用してクエリ結果を Timestream for LiveAnalytics から S3 にエクスポートする Amazon Timestream for LiveAnalytics では、`UNLOAD` ステートメントを使用して、費用対効果の高い安全な方法でクエリ結果を Amazon S3 にエクスポートできるようになりました。`UNLOAD` ステートメントを使用して、時系列データを Apache Parquet 形式またはカンマ区切り値 (CSV) 形式で選択した S3 バケットにエクスポートできるようになりました。これにより、時系列データを他のサービスと柔軟に保存、組み合わせ、分析できます。`UNLOAD` ステートメントを使用すると、圧縮された方法でデータをエクスポートできるため、転送されるデータと必要なストレージ領域が減少します。`UNLOAD` は、データのエクスポート時に選択した属性に基づくパーティショニングもサポートし、パフォーマンスが向上し、データにアクセスするダウンストリームサービスの処理時間が短縮されます。さらに、Amazon S3 マネージドキー (SSE-S3) または AWS Key Management Service (AWS KMS) マネージドキー (SSE-KMS) を使用して、エクスポートされたデータを暗号化できます。 ## Timestream for LiveAnalytics の UNLOAD の利点 `UNLOAD` ステートメントを使用する主な利点は次のとおりです。 + **運用の容易さ** – `UNLOAD` ステートメントを使用すると、Apache Parquet 形式または CSV 形式で 1 回のクエリリクエストでギガバイト規模のデータをエクスポートできるため、ダウンストリームの処理ニーズに最適な形式を柔軟に選択でき、データレイクの構築が容易になります。 + **安全性とコスト効率** – `UNLOAD` ステートメントは、データを圧縮された方法で S3 バケットにエクスポートし、カスタマーマネージドキーを使用してデータを暗号化 (SSE-KMS または SSE\$1S3) して、データストレージコストを削減し、不正アクセスから保護する機能を提供します。 + **パフォーマンス** – `UNLOAD` ステートメントを使用して、S3 バケットにエクスポートするときにデータをパーティション化できます。データのパーティション化により、ダウンストリームサービスはデータを並行して処理できるので、処理時間を短縮できます。さらに、ダウンストリームサービスは必要なデータのみを処理できるので、必要な処理リソースが減少し、関連するコストが削減されます。 ## Timestream for LiveAnalytics の UNLOAD のユースケース `UNLOAD` ステートメントを使用して、S3 バケットにデータを書き込むことができます。 + **データウェアハウスの構築** – 数ギガバイトのクエリ結果を S3 バケットにエクスポートし、時系列データをデータレイクに簡単に追加できます。Amazon Athena や Amazon Redshift などのサービスを使用して、時系列データと他の関連データを組み合わせ、複雑なビジネスインサイトを得ることができます。 + **AI および ML データパイプラインの構築** – `UNLOAD` ステートメントを使用すると、時系列データにアクセスする機械学習モデルのデータパイプラインを簡単に構築できるため、Amazon SageMaker や Amazon EMR などのサービスで時系列データを簡単に使用できます。 + **ETL 処理の簡素化** – S3 バケットにデータをエクスポートすると、データに対して抽出、変換、ロード (ETL) オペレーションを実行するプロセスを簡素化できるため、 Glue AWS などのサードパーティーのツールや AWS サービスをシームレスに使用してデータを処理および変換できます。 # 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\$1BY 句 ``` 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 列でパーティショニングされたエクスポートされたデータ ![\[Folder structure showing channels: Direct, Organic search, Other, Referral, and Social media.\]](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\$1S3 および SSE\$1KMS 暗号化がサポートされています。SSE\$1S3 は、256 ビットの高度暗号化標準 (AES) 暗号化を使用してデータを暗号化する Amazon S3 によるサーバー側の暗号化です。SSE\$1KMS は、カスタマーマネージドキーを使用してデータを暗号化するサーバー側の暗号化です。 KMS\$1KEY ``` kms_key = '' ``` KMS キーは、エクスポートされたクエリ結果を暗号化するためのユーザー定義のキーです。KMS キーは AWS Key Management Service (AWS KMS) によって安全に管理され、Amazon S3 のデータファイルの暗号化に使用されます。 FIELD\$1DELIMITER ``` field_delimiter ='' , default: (,) ``` CSV 形式でデータをエクスポートするとき、このフィールドはパイプ文字 (\$1)、カンマ (,)、タブ (\$1t) など、出力ファイルのフィールドを区切るために使用する単一の ASCII 文字を指定します。CSV ファイルのデフォルトの区切り文字はコンマ文字です。データの値に選択した区切り文字が含まれている場合、区切り文字は引用符で囲まれます。例えば、データ内の値に `Time,stream` が含まれている場合、この値はエクスポートされたデータで `"Time,stream"` として引用符で囲まれます。Timestream for LiveAnalytics で使用される引用文字は二重引用符 (") です。 CSV にヘッダーを含める場合は、キャリッジリターン文字 (ASCII 13、16 進数 `0D`、テキスト '\$1r') または改行文字 (ASCII 10、16 進数 0A、テキスト '\$1n') を `FIELD_DELIMITER` として指定しないでください。これにより、多くのパーサーが生成された CSV 出力でヘッダーを正しく解析できなくなるためです。 ESCAPED\$1BY ``` escaped_by = '', default: (\) ``` CSV 形式でデータをエクスポートする場合、このフィールドは S3 バケットに書き込まれたデータファイルでエスケープ文字として扱う文字を指定します。エスケープは以下のようなシナリオで発生します。 1. 値自体に引用文字 (") が含まれている場合、エスケープ文字を使用してエスケープされます。例えば、値が `Time"stream` で、(\$1) が設定されたエスケープ文字である場合、`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\$1HEADER ``` include_header = 'true' , default: 'false' ``` CSV 形式でデータをエクスポートする場合、このフィールドではエクスポートされた CSV データファイルの最初の行として列名を含めることができます。 使用できる値は「true」と「false」で、デフォルト値は「false」です。`escaped_by` や `field_delimiter` などのテキスト変換オプションは、ヘッダーにも適用されます。 ヘッダーを含める場合、キャリッジリターン文字 (ASCII 13、16 進 0D、テキスト '\$1r') または改行文字 (ASCII 10、16 進 0A、テキスト '\$1n') を `FIELD_DELIMITER` として選択しないことが重要です。これらの文字を選択すると、多くのパーサーが生成された CSV 出力でヘッダーを正しく解析できなくなるためです。 MAX\$1FILE\$1SIZE ``` 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\$1name/\$1\$1metadata.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 クエリ言語のデータ型すべてをサポートします。 # Timestream for LiveAnalytics の UNLOAD の前提条件 以下は、Timestream for LiveAnalytics から `UNLOAD` を使用して S3 にデータを書き込むための前提条件です。 + `UNLOAD` コマンドで使用する Timestream for LiveAnalytics テーブルからデータを読み取るアクセス許可が必要です。 + LiveAnalytics リソースの Timestream と同じ AWS リージョンに Amazon S3 バケットが必要です。 + 選択した S3 バケットについて、[S3 バケットポリシー](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html)に、Timestream for LiveAnalytics によるデータのエクスポートを許可するアクセス許可も付与されていることを確認します。 + `UNLOAD` クエリの実行に使用される認証情報には、Timestream for LiveAnalytics が S3 にデータを書き込めるようにするために必要な AWS Identity and Access Management (IAM) アクセス許可が必要です。ポリシーの例は次のとおりです。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "timestream:Select", "timestream:ListMeasures", "timestream:WriteRecords", "timestream:Unload" ], "Resource": "arn:aws:timestream:us-east-2:111122223333:database/database_name/table/table_name" }, { "Effect": "Allow", "Action": [ "s3:GetBucketAcl", "s3:PutObject", "s3:GetObject", "s3:AbortMultipartUpload" ], "Resource": [ "arn:aws:s3:::S3_Bucket_Created", "arn:aws:s3:::S3_Bucket_Created/*" ] } ] } ``` ------ これらの S3 書き込みアクセス許可に関する追加のコンテキストについては、「[Amazon Simple Storage Service ユーザーガイド](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html#mpuAndPermissions)」を参照してください。エクスポートされたデータの暗号化に KMS キーを使用している場合は、必要な追加の IAM ポリシーについて次を参照してください。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:DescribeKey", "kms:Decrypt", "kms:GenerateDataKey*" ], "Resource": "arn:aws:kms:us-east-2:111122223333:key/*", "Condition": { "ForAnyValue:StringLike": { "kms:ResourceAliases": "alias/Alias_For_Generated_Key" } } }, { "Effect": "Allow", "Action": [ "kms:CreateGrant" ], "Resource": "arn:aws:kms:us-east-2:111122223333:key/*", "Condition": { "ForAnyValue:StringEquals": { "kms:EncryptionContextKeys": "aws:timestream:database_name" }, "Bool": { "kms:GrantIsForAWSResource": true }, "StringLike": { "kms:ViaService": "timestream.us-east-2.amazonaws.com" }, "ForAnyValue:StringLike": { "kms:ResourceAliases": "alias/Alias_For_Generated_Key" } } } ] } ``` ------ # Timestream for LiveAnalytics の UNLOAD のベストプラクティス UNLOAD コマンドに関連するベストプラクティスを次に示します。 + `UNLOAD` コマンドを使用して S3 バケットにエクスポートできるデータ量に制限はありません。ただし、クエリは 60 分でタイムアウトするため、1 回のクエリでエクスポートするデータは 60 GB 以下にすることをお勧めします。60 GB を超えるデータをエクスポートする必要がある場合は、ジョブを複数のクエリに分割します。 + 何千ものリクエストを S3 に送信してデータをアップロードできますが、書き込みオペレーションを複数の S3 プレフィックスに並列化することをお勧めします。[こちら](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html)のドキュメントを参照してください。複数のリーダー/ライターが同じフォルダにアクセスすると、S3 API コールレートがスロットリングされる場合があります。 + プレフィックスの定義には S3 キーの長さの制限があるため、特に `partitioned_by` 句を使用する場合は、バケット名とフォルダ名を 10～15 文字にすることをお勧めします。 + `UNLOAD` ステートメントを含むクエリに対して 4XX または 5XX を受け取ると、部分的な結果が S3 バケットに書き込まれる可能性があります。Timestream for LiveAnalytics は、バケットからデータを削除しません。同じ S3 送信先で別の `UNLOAD` クエリを実行する前に、失敗したクエリによって作成されたファイルを手動で削除することをお勧めします。失敗したクエリによって書き込まれたファイルは、対応する `QueryExecutionId` で識別できます。クエリが失敗した場合、Timestream for LiveAnalytics はマニフェストファイルを S3 バケットにエクスポートしません。 + Timestream for LiveAnalytics は、マルチパートアップロードを使用してクエリ結果を S3 にエクスポートします。UNLOAD ステートメントを含むクエリについて Timestream for LiveAnalytics から 4XX または 5XX を受け取ると、Timestream for LiveAnalytics はマルチパートアップロードのベストエフォート中止を実行しますが、一部の不完全なパートが残っている可能性があります。したがって、[こちら](https://aws.amazon.com/blogs/aws-cloud-financial-management/discovering-and-deleting-incomplete-multipart-uploads-to-lower-amazon-s3-costs/)のガイドラインに従って、S3 バケット内の不完全なマルチパートアップロードの自動クリーンアップを設定することをお勧めします。 ## CSV パーサーを使用して CSV 形式でデータにアクセスするための推奨事項 + CSV パーサーでは、区切り文字、エスケープ文字、引用符文字を同じ文字にすることはできません。 + 一部の CSV パーサーでは配列などの複雑なデータ型を解釈できないため、JSON デシリアライザーを使用して解釈することをお勧めします。 ## Parquet 形式でデータにアクセスするための推奨事項 1. ユースケースにおいてスキーマ (列名) に UTF-8 文字のサポートが必要な場合は、[Parquet-mr ライブラリ](https://github.com/apache/parquet-mr)を使用することをお勧めします。 1. 結果のタイムスタンプは 12 バイト整数 (INT96) で表されます。 1. 時系列は `array>` として表され、他のネストされた構造は Parquet 形式でサポートされている対応するデータ型を使用します。 ## partition\$1by 句の使用 + `partitioned_by` フィールドで使用される列は、選択クエリの最後の列である必要があります。`partitioned_by` フィールドで複数の列が使用されている場合、列は選択クエリの最後の列で、`partition_by` フィールドで使用されるのと同じ順序である必要があります。 + データのパーティション化に使用される列値 (`partitioned_by` フィールド) には、ASCII 文字のみを含めることができます。Timestream for LiveAnalytics では値に UTF-8 文字を使用できますが、S3 ではオブジェクトキーとして ASCII 文字のみがサポートされています。 # Timestream for LiveAnalytics の UNLOAD のユースケース例 e コマースウェブサイトのユーザーセッションメトリクス、トラフィックソース、製品購入をモニタリングしているとします。Timestream for LiveAnalytics を使用して、ユーザーの行動、製品の販売に関するリアルタイムのインサイトを取得し、顧客をウェブサイトに誘導するトラフィックチャネル (オーガニック検索、ソーシャルメディア、直接トラフィック、有料キャンペーンなど) に対するマーケティング分析を実行します。 **Topics** + [パーティションなしでデータをエクスポートする](#export-unload-example-sample-1) + [チャネル別のデータのパーティション化](#export-unload-example-sample-2) + [イベントによるデータのパーティショニング](#export-unload-example-sample-3) + [チャネルとイベントの両方によるデータのパーティショニング](#export-unload-example-sample-4) + [マニフェストファイルとメタデータファイル](#export-unload-example-manifest-metadata) + [Glue クローラーを使用した Glue データカタログの構築](#export-unload-example-using-glue-crawlers) ## パーティションなしでデータをエクスポートする 過去 2 日間のデータを CSV 形式でエクスポートする必要があるとします。 ``` 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:///withoutpartition' WITH ( format='CSV', compression='GZIP') ``` ## チャネル別のデータのパーティション化 過去 2 日間のデータを CSV 形式でエクスポートしたいが、各トラフィックチャネルのデータを別のフォルダに保持する必要があるとします。これを行うには、次に示すように `channel` 列を使用してデータをパーティション化する必要があります。 ``` 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:///partitionbychannel/' WITH ( partitioned_by = ARRAY ['channel'], format='CSV', compression='GZIP') ``` ## イベントによるデータのパーティショニング 過去 2 日間のデータを CSV 形式でエクスポートしたいが、各イベントのデータを別々のフォルダに保持する必要があるとします。これを行うには、次に示すように `event` 列を使用してデータをパーティション化する必要があります。 ``` UNLOAD(SELECT user_id, ip_address, channel, session_id, measure_name, time, query, quantity, product_id, event FROM sample_clickstream.sample_shopping WHERE time BETWEEN ago(2d) AND now()) TO 's3:///partitionbyevent/' WITH ( partitioned_by = ARRAY ['event'], format='CSV', compression='GZIP') ``` ## チャネルとイベントの両方によるデータのパーティショニング 過去 2 日間のデータを CSV 形式でエクスポートしたいが、各チャネルおよびチャネル内のデータの各イベントを別のフォルダに保存する必要があるとします。これを行うには、次に示すように、`channel` と `event` 列の両方を使用してデータをパーティショニングする必要があります。 ``` UNLOAD(SELECT user_id, ip_address, session_id, measure_name, time, query, quantity, product_id, channel,event FROM sample_clickstream.sample_shopping WHERE time BETWEEN ago(2d) AND now()) TO 's3:///partitionbychannelevent/' WITH ( partitioned_by = ARRAY ['channel','event'], format='CSV', compression='GZIP') ``` ## マニフェストファイルとメタデータファイル ### マニフェストファイル マニフェストファイルは、UNLOAD 実行でエクスポートされるファイルのリストに関する情報を提供します。マニフェストファイルは、ファイル名 `S3://bucket_name/__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\$1name/\$1\$1metadata.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` と同じ構造です。 ## Glue クローラーを使用した Glue データカタログの構築 1. 管理者認証情報を使用してアカウントにログインし、次の検証を行います。 1. [こちら](https://docs.aws.amazon.com/glue/latest/ug/tutorial-add-crawler.html)に記載されているガイドラインを使用して、Glue データベース用のクローラーを作成します。データソースに提供される S3 フォルダは、`s3://my_timestream_unloads/results` などの `UNLOAD` 結果フォルダである必要があります。 1. [こちら](https://docs.aws.amazon.com/glue/latest/ug/tutorial-add-crawler.html#tutorial-add-crawler-step2)のガイドラインに従ってクローラーを実行します。 1. Glue テーブルを表示します。 + **[AWS Glue]** → **[テーブル]** に移動します。 + クローラーの作成時にテーブルプレフィックスを指定して作成された新しいテーブルが表示されます。 + テーブルの詳細ビューをクリックすると、スキーマとパーティションの情報を表示できます。 以下は、 Glue データカタログを使用する AWS 他の AWS サービスとオープンソースプロジェクトです。 + **Amazon Athena** – 詳細については、「Amazon Athena ユーザーガイド」の「[Athena でのテーブル、データベース、およびデータカタログの理解](https://docs.aws.amazon.com/athena/latest/ug/understanding-tables-databases-and-the-data-catalog.html)」を参照してください。 + **Amazon Redshift Spectrum** – 詳細については、「Amazon Redshift データベース開発者ガイド」で[Amazon Redshift Spectrum を使用した外部データへのクエリの実行方法](https://docs.aws.amazon.com/redshift/latest/dg/c-using-spectrum.html)を確認してください。 + **Amazon EMR** – 詳細については、[「Amazon EMR 管理ガイド」の「 Glue Data Catalog AWS への Amazon EMR アクセスにリソースベースのポリシー](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-iam-roles-glue.html)を使用する」を参照してください。 + **AWS Apache Hive メタストア用の Glue データカタログクライアント** – この GitHub プロジェクトの詳細については、「[AWS Apache Hive メタストア用の Glue データカタログクライアント](https://github.com/awslabs/aws-glue-data-catalog-client-for-apache-hive-metastore)」を参照してください。 # Timestream for LiveAnalytics の UNLOAD の制限 `UNLOAD` コマンドに関連する制限を次に示します。 + `UNLOAD` ステートメントを使用するクエリの同時実行数は、1 クエリ/秒 (QPS) です。このクエリレートを超えると、スロットリングが発生する可能性があります。 + `UNLOAD` ステートメントを含むクエリは、クエリごとに最大 100 個のパーティションをエクスポートできます。エクスポートされたデータのパーティショニングに使用する前に、選択した列の明確な数を確認することをお勧めします。 + `UNLOAD` ステートメントを含むクエリは 60 分後にタイムアウトします。 + `UNLOAD` ステートメントが Amazon S3 で作成するファイルの最大サイズは 78 GB です。 Timestream for LiveAnalytics の他の制限については、「[クォータデフォルトのクォータ](ts-limits.md)」を参照してください。