Azure Data Explorer に履歴データを取り込む方法

[アーティクル]
11/23/2024

Azure Data Explorer にオンボードする場合の一般的なシナリオは、履歴データ (バックフィルとも呼ばれます) を取り込む場合です。このプロセスには、既存のストレージシステムからテーブルへのデータの取り込み ( 拡張のコレクション) が含まれます。

creationTime インジェストプロパティを使用して履歴データを取り込みエクステントの作成時間をデータの作成に設定することをお勧めします。インジェストのパーティション分割条件として作成時間を使用すると、 cache と retention ポリシーに従ってデータが期限切れになり、時間フィルターがより効率的になります。

既定では、エクステントの作成時間はデータが取り込まれる時刻に設定され、予期した動作が生成されない可能性があります。たとえば、キャッシュ期間が 30 日で、リテンション期間が 2 年のテーブルがあるとします。通常のフローでは、生成時に取り込まれたデータは 30 日間キャッシュされ、コールドストレージに移動されます。 2 年後、作成時間に基づいて、古いデータは一度に 1 日ずつ削除されます。ただし、2 年間の履歴データを取り込む場合、既定では、データは、データが取り込まれる時刻として作成時間でマークされます。これにより、次の理由で目的の結果が得られない可能性があります。

すべてのデータはキャッシュに格納され、予想よりも多くのキャッシュを使用して 30 日間そこにとどまります。
古いデータは一度に 1 日ずつ削除されません。そのため、データは必要以上に長くクラスターに保持され、2 年後にすべて一度に削除されます。
ソースシステムの日付別にグループ化されたデータは、同じ範囲で非効率的なクエリにつながる一緒に格納される可能性があります。

既定の作成時刻を使用して履歴データを取り込む場合の予想される結果と実際の結果を示す図。

この記事では、履歴データをパーティション分割する方法について説明します。

インジェスト中に creationTime インジェストプロパティを使用する (推奨)

可能な場合は、 creationTime インジェストプロパティを使用して履歴データを取り込みます。これにより、ファイルまたは BLOB パスからエクステントを抽出してエクステントの作成時間を設定できます。フォルダー構造で作成日パターンが使用されていない場合は、作成時刻を反映するようにファイルまたは BLOB パスを再構築することをお勧めします。この方法を使用すると、正しい作成時間でデータがテーブルに取り込まれるので、キャッシュと保持期間が正しく適用されます。

Note

既定では、エクステントは作成 (インジェスト) の時間でパーティション分割されます。ほとんどの場合、データパーティション分割ポリシーを設定する必要はありません。
インジェスト後のパーティション分割ポリシーの使用

creationTime インジェストプロパティを使用できない場合 (たとえば、Azure Cosmos DB コネクタを使用してデータをしている場合作成時間を制御できない場合や、フォルダー構造を再構築できない場合は、インジェスト後にテーブルを再パーティション分割して、パーティション分割ポリシーを使用して同じ効果を実現できます。ただし、このメソッドでは、ポリシープロパティを最適化するために試行とエラーが必要になる場合があり、 creationTime インジェストプロパティを使用する場合よりも効率が低くなります。 creationTime インジェストプロパティを使用できない場合にのみ、この方法をお勧めします。

前提条件

Microsoft アカウントまたは Microsoft Entra ユーザー ID。 Azure サブスクリプションは不要です。
Azure Data Explorer クラスターとデータベース。クラスターとデータベースを作成します。
ストレージアカウント。
インジェスト中にcreationTime インジェストプロパティを使用する推奨される方法については、LightIngest インストールします。

履歴データを取り込む

インジェスト中に、 creationTime インジェストプロパティを使用して履歴データをパーティション分割することを強くお勧めします。ただし、この方法を使用できない場合は、パーティション分割ポリシーを使用して、インジェスト後にテーブルを再パーティション分割できます。

インジェスト中 (推奨)
インジェスト後

LightIngest は、既存のストレージシステムから Azure Data Explorer に履歴データを読み込むのに役立ちます。 Command-line 引数の一覧を使用して独自のコマンドを作成できますがこの記事では、インジェストウィザードを使用してこのコマンドを自動生成する方法について説明します。コマンドの作成だけでなく、このプロセスを使用して、新しいテーブルの作成およびスキーママッピングの作成も可能です。このツールは、データセットからスキーママッピングを推論します。

宛先

Azure Data Explorer Web UI で、左側のメニューから Query を選択します。
データを取り込むデータベースを右クリックし、 LightIngestを選択します。

Ingest data ウィンドウが開き、[Destination] タブが選択されています。 [クラスター] と [データベース] の各フィールドには、自動的に値が設定されます。
ターゲットテーブルを選択します。新しいテーブルにデータを取り込む場合は、 [新しいテーブル] を選択し、テーブル名を入力します。

Note

テーブル名には、スペース、英数字、ハイフン、アンダースコアを含め、最大 1024 文字を使用できます。特殊文字はサポートされていません。
[Next: Source](次へ: ソース) を選択します。

ソース

[ソースの選択で URL の追加またはコンテナーの選択を選択。
- URL を追加する場合は、 ソースへのリンクで、コンテナーへのアカウントキーまたは SAS URL を指定します。 SAS URL 手動または自動で作成できます。
- ストレージアカウントからコンテナーを選択する場合は、ドロップダウンメニューから Storage サブスクリプション、 Storage アカウント、 Container を選択します。
Note

インジェストでは、最大で 6 GB のファイルサイズがサポートされます。 100 MB から 1 GB の間のファイルを取り込むことをお勧めします。
[ Advanced 設定 を選択して、LightIngest を使用してインジェストプロセスの追加設定を定義します。

Advanced 構成 ペインで、次の表に従って LightIngest 設定を定義します。

ツール LightIngest に関連するインジェスト処理の追加設定を示す [詳細構成] ウィンドウのスクリーンショット。

プロパティ	説明
作成時間パターン	たとえば、コンテナーのフォルダー構造に基づいて日付を適用する場合など、作成されたエクステントのインジェスト時間プロパティをパターンでオーバーライドする場合に指定します。「作成時刻のパターン」も参照してください。
BLOB 名パターン	取り込まれたファイルを識別するために使用するパターンを指定します。指定されたコンテナー内の blob 名のパターンに一致するすべてのファイルを取り込みます。ワイルドカードがサポートされます。二重引用符で囲むのをお勧めします。
Tag	取り込まれたデータに割り当てられたタグ。タグには、任意の文字列を使用できます。
ファイルの量を制限する	取り込むことができるファイルの数を指定します。指定された数を上限として、blob 名パターンに一致する最初の `n` 個のファイルを取り込みます。
インジェストが完了するまで待たない	設定すると、インジェスト処理を監視せずに、取り込み用の blob をキューに挿入します。設定されていない場合は、LightIngest は、取り込みが完了するまでインジェストの状態のポーリングを続行します。
選択した項目のみを表示する	コンテナー内のファイルを一覧表示しますが、取り込みません。

[ソース]タブに戻ソースを選択します。
1. 必要に応じて、 [ファイルフィルター] を選択して、特定のフォルダーパスまたは特定のファイル拡張子を持つファイルのみを取り込むためにデータをフィルター処理します。
  
  既定では、コンテナー内のいずれかのファイルがランダムに選択され、テーブルのスキーマを生成するために使用されます。
2. 必要に応じて、 Schema 定義ファイルで、使用するファイルを指定できます。
テーブル列の構成を表示および編集するには、[Next: Schema]$次へ: スキーマ$ を選択します。

[スキーマ]

[スキーマ] タブには、データのプレビューが表示されます。

LightIngest コマンドを生成するには、 Next: Start Ingestion を選択します。

必要に応じて、次の操作を行います。

ドロップダウンメニューから目的の形式を選択して自動的に推論されるData 形式を変更します。
自動的に推論される マップ名を変更します。英数字とアンダースコアを使用できます。スペース、特殊文字、ハイフンはサポートされません。
既存のテーブルを使用する場合、選択した形式とテーブルスキーマが一致する場合は、現在のテーブルスキーマを保持できます。
[コマンドビューアー] を選択し、入力から生成される自動コマンドを表示してコピーします。
列を編集します。 Partial データプレビューで、列のドロップダウンメニューを選択して、テーブルのさまざまな側面を変更します。

テーブルに加えることができる変更は、次のパラメーターによって異なります。

テーブルの種類が新規かまたは既存か
マッピングの種類が新規かまたは既存か

テーブルの種類です。	マッピングの種類	使用可能な調整
新しいテーブル	新しいマッピング	データ型の変更、列名の変更、列の削除、昇順で並べ替え、降順で並べ替え
既存のテーブル	新しいマッピング	新しい列 (データ型の変更、名前の変更、更新が可能) 新しい列、昇順で並べ替え、降順で並べ替え
	既存のマッピング	昇順で並べ替え、降順で並べ替え

注意

新しい列を追加するとき、または列を更新するときに、マッピング変換を変更できます。詳細については、マッピング変換に関するページを参照してください。

取り込み

テーブル、マッピング、LightIngest コマンドに緑色のチェックマークが付いたら、Generated コマンド ボックスの右上にある copy アイコンを選択して、生成された LightIngest コマンドをコピーします。

$コマンドが生成された [Summary]$概要$ タブのスクリーンショット。生成されたコマンドボックスの上にあるコピーアイコンを使用して、コマンドをコピーできます。$

Note

必要に応じて、LightIngest ツールをダウンロード ダウンロードを選択します。
インジェストプロセスを完了するには、コピーしたコマンドを使用して LightIngest を実行する必要があります。

手順 1: 再パーティション分割の準備

古いデータを許可するように保持ポリシーを調整します。次の例では、テーブル MyTable のアイテム保持ポリシーを 10 年に設定します。
```
.alter-merge table MyTable policy retention softdelete = 3650d recoverability = enabled
```
インジェスト後に再パーティション分割できるのはホットデータのみであるため、再パーティション分割のためにすべてのデータがホットキャッシュに入るようにキャッシュポリシーを調整します。次の例では、テーブル MyTable のキャッシュを 10 年に設定します。
```
.alter table MyTable policy caching hot = 3650d
```
重要

キャッシュポリシーを増やすと、通常の操作よりもかなり多くのホットキャッシュが使用され、コストが増加する可能性があります。

手順 2: 再パーティション分割を開始する

Timestampという名前の列でデータをパーティション分割するパーティション分割ポリシーを作成します。次の例では、テーブル MyTable のパーティション分割ポリシーを、 Timestampという名前の列でパーティション分割するように設定します。
```
.alter table MyTable policy partitioning
```
{
  "EffectiveDateTime" : "1970-01-01T00:00:00",
  "PartitionKeys": [
    {
      "ColumnName": "Timestamp",
      "Kind": "UniformRange",
      "Properties": {
        "Reference": "1970-01-01T00:00:00",
        "RangeSize": "1.00:00:00",
        "OverrideCreationTime": true
      }
    }
  ]
}
```
```
パーティション分割ポリシーのプロパティの詳細については、「パーティションのプロパティを参照してください。インジェストの履歴については、次のプロパティを設定する方法が重要です。
- 再パーティション分割をトリガーするには、 EffectiveDateTime プロパティをインジェストの開始より前の日付に設定する必要があります。
- データが 1 日のバケットに再分割されるように、 RangeSize は 1 日に設定されます。ただし、データに合わせてこの値を設定する必要があります。たとえば、1 日に数 GB 未満のデータがある場合は、より大きな値を設定することを検討してください。
- OverrideCreationTime を true に設定する必要がありますデータを日バケットに再パーティション分割した後、エクステントがその日に作成時刻としてマークされるようにします。
マージポリシーを設定して、14 日より前のエクステントを含むすべてのエクステントのマージを許可します。再パーティション分割プロセスでは 14 日より前のエクステントが作成されるため、このポリシーの設定は重要です。これは、既定ではマージプロセスによって除外されます。
```
.alter table MyTable policy merge
```
{
  "Lookback": {
    "Kind": "HotCache"
  }
}
```
```
.show データベース・エクステントのパーティション統計コマンドを使用して、再パーティション分割の進行状況を監視します。返された結果で、再パーティション分割しているテーブルを探し、 PartitionedRowPercentage 列を監視します。 PartitionedRowPercentage列の値が100されると、再パーティション分割が完了します。

手順 3: 再パーティション分割後のクリーンアップ

再パーティション分割が完了したら、前の手順で設定したポリシーをクリーンアップできます。

パーティション分割ポリシーを削除します。
```
.delete table MyTable policy partitioning
```
マージポリシーを削除します。
```
.delete table MyTable policy merge
```

キャッシュポリシーを削除または設定します。

// Remove the caching policy
.delete table MyTable policy caching
// OR set the caching policy to your desired value
.alter table MyTable policy caching hot = 90d

アイテム保持ポリシーを削除または設定します。

// Remove the retention policy
.delete table MyTable policy retention
// OR set the retention policy to your desired value
.alter-merge table MyTable policy retention softdelete = 30d recoverability = enabled

Azure Data Explorer でデータのクエリを実行する

次の方法で共有