次の方法で共有

インジェスト マッピング

  • [アーティクル]

適用対象: ✅Microsoft Fabric✅Azure データ エクスプローラー

インジェスト マッピングは、インジェスト中に、受信データをテーブル内の列にマップするために使用されます。

データ エクスプローラーでは、行指向 (CSV、JSON、AVRO、W3CLOGFILE) と列指向 (Parquet および ORC) の両方の異なる種類のマッピングがサポートされています。

インジェスト マッピングは、取り込みコマンドで定義することも、事前に作成された して、ingestionMappingReference パラメーターを使用して取り込みコマンドから参照することもできます。 マッピングを指定しなくてもインジェストが可能です。 詳細については、 識別マッピングを参照してください。

マッピング リスト内の各要素は、次の 3 つのフィールドから構成されます。

プロパティ Required 説明
列 ✔️ テーブル内のターゲット列名。
DataType マップされた列がテーブルにまだ存在しない場合に作成するデータ型。
プロパティ 各特定のマッピングの種類のページで説明されているように、各マッピングに固有のプロパティを含むプロパティ バッグ。

重要

キューに入ったインジェストの場合:

  • マッピングで参照されているテーブルがデータベースに存在しない場合は、すべての列に有効なデータ型が指定されているため、自動的に作成されます。
  • マッピングで参照されている列がテーブルに存在しない場合、列に対して有効なデータ型が指定されている場合、その列に対して最初にデータが取り込まれると、その列が最後の列としてテーブルに自動的に追加されます。 マッピングに新しい列を追加するには、 .alter インジェスト マッピング コマンドを使用します。
  • データは、インジェスト プロパティを使用してバッチ処理されます。 異なる ConstValue 値など、使用されるインジェスト マッピング プロパティが異なるほど、インジェストの断片化が増え、パフォーマンスが低下する可能性があります。

サポートされているマッピングの種類

次の表は、特定の形式の外部データの取り込みまたはクエリを実行するときに使用するマッピングの種類を定義します。

データ形式 マッピングの種類
CSV CSV マッピング
TSV CSV マッピング
TSVe CSV マッピング
PSV CSV マッピング
SCSV CSV マッピング
SOHsv CSV マッピング
TXT CSV マッピング
RAW CSV マッピング
JSON JSON マッピング
AVRO AVRO マッピング
APACHEAVRO AVRO マッピング
Parquet Parquet マッピング
ORC ORC マッピング
W3CLOGFILE W3CLOGFILE マッピング

インジェスト マッピングの例

次の例では、次のスキーマで RawEvents テーブルを使用します。

.create table RawEvents (timestamp: datetime, deviceId: guid, messageId: guid, temperature: decimal, humidity: decimal)

単純なマッピング

次の例は、取り込みコマンドでマッピングが定義されているインジェストを示しています。 このコマンドは、URL から RawEvents テーブルに JSON ファイルを取り込みます。 マッピングでは、JSON ファイル内の各フィールドへのパスを指定します。

.ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') 
    with (
            format = "json",
            ingestionMapping =
            ```
            [ 
              {"column":"timestamp","Properties":{"path":"$.timestamp"}},
              {"column":"deviceId","Properties":{"path":"$.deviceId"}},
              {"column":"messageId","Properties":{"path":"$.messageId"}},
              {"column":"temperature","Properties":{"path":"$.temperature"}},
              {"column":"humidity","Properties":{"path":"$.humidity"}}
            ]
            ```
          )

ingestionMappingReference を使用したマッピング

事前に作成されたマッピングを使用して同じ JSON ファイルをマップするには、次のコマンドを使用して RawEventMapping インジェスト マッピング参照を作成します。

.create table RawEvents ingestion json mapping 'RawEventMapping' 
  ```
  [ 
    {"column":"timestamp","Properties":{"path":"$.timestamp"}},
    {"column":"deviceId","Properties":{"path":"$.deviceId"}},
    {"column":"messageId","Properties":{"path":"$.messageId"}},
    {"column":"temperature","Properties":{"path":"$.temperature"}},
    {"column":"humidity","Properties":{"path":"$.humidity"}}
  ]
  ```

次のコマンドを使用して、RawEventMapping インジェスト マッピング参照を使用して JSON ファイルを取り込みます。

.ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') 
  with (
          format="json",
          ingestionMappingReference="RawEventMapping"
        )

ID のマッピング

ingestionMapping または ingestionMappingReference プロパティを指定せずにインジェストを行うことができます。 データは、テーブルのスキーマから派生した ID データ マッピングを使用してマップされます。 テーブル スキーマは変わりません。 format プロパティを指定する必要があります ingestion 形式を参照してください。

形式の種類 形式 マッピング ロジック
区切り記号で区切られた形式や単一行の形式など、列の順序が定義された表形式のデータ形式。 CSV、TSV、TSVe、PSV、SCSV、Txt、SOHsv、Raw すべてのテーブル列は、データ ソースに表示される順序でデータ列にマップされます。 列のデータ型はテーブル スキーマから取得されます。
名前付き列または名前付きフィールドを含むレコードを書式設定します。 JSON、Parquet、Avro、ApacheAvro、Orc、W3CLOGFILE すべてのテーブル列は、同じ名前のデータ列またはレコード フィールドにマップされます (大文字と小文字は区別されます)。 列のデータ型はテーブル スキーマから取得されます。

警告

テーブル スキーマとデータの構造 (列またはフィールドのデータ型、列またはフィールドの名前、数など) が一致しないと、取り込まれるデータが空または不正確になる可能性があります。

マッピング変換

一部のデータ形式マッピング (Parquet、JSON、AVRO) では、単純で便利な取り込み時間変換がサポートされています。 取り込み時により複雑な処理を必要とするシナリオでは、更新ポリシーを使用します。これにより、KQL 式を使用した簡易処理が可能になります。

パスに依存する変換 説明 条件
PropertyBagArrayToDictionary {events:[{"n1":"v1"},{"n2":"v2"}]}などのプロパティの JSON 配列をディクショナリに変換し、{"n1":"v1","n2":"v2"}などの有効な JSON ドキュメントにシリアル化します。 JSON、Parquet、AVRO、およびORCマッピングの種類で使用できます。
SourceLocation データを提供したストレージ成果物の名前、String 型 (たとえば、BLOB の "BaseUri" フィールド)。 CSV、JSON、Parquet、AVRO、ORC、およびW3CLOGFILEマッピングの種類で使用できます。
SourceLineNumber そのストレージ成果物を基準としたオフセット、Long 型 ('1' から始まり、新しいレコードごとに増分)。 CSV、JSON、Parquet、AVRO、ORC、およびW3CLOGFILEマッピングの種類で使用できます。
DateTimeFromUnixSeconds unix-time (1970-01-01 以降の秒) を表す数値を UTC 日時文字列に変換します。 CSV、JSON、Parquet、AVRO、およびORCマッピングの種類で使用できます。
DateTimeFromUnixMilliseconds unix-time (1970-01-01 以降のミリ秒) を表す数値を UTC 日時文字列に変換します。 CSV、JSON、Parquet、AVRO、およびORCマッピングの種類で使用できます。
DateTimeFromUnixMicroseconds unix-time (1970-01-01 以降のマイクロ秒) を表す数値を UTC 日時文字列に変換します。 CSV、JSON、Parquet、AVRO、およびORCマッピングの種類で使用できます。
DateTimeFromUnixNanoseconds unix-time (1970-01-01 以降のナノ秒) を表す数値を UTC 日時文字列に変換します。 CSV、JSON、Parquet、AVRO、およびORCマッピングの種類で使用できます。
DropMappedFields JSON ドキュメント内のオブジェクトを列にマップし、他の列マッピングによって既に参照されている入れ子になったフィールドをすべて削除します。 JSON、Parquet、AVRO、およびORCマッピングの種類で使用できます。
BytesAsBase64 データをバイト配列として扱い、base64 でエンコードされた文字列に変換します。 マッピングの種類 AVRO 使用できます。 ApacheAvro形式の場合、マップされたデータ フィールドのスキーマ型は bytes または avro 型fixedする必要があります。 Avro形式の場合、フィールドは [0 - 255] 範囲のバイト値を含む配列である必要があります。 null は、データが有効なバイト配列を表さない場合に取り込まれます。

マッピング変換の例

DropMappedFields 変換：

次の JSON コンテンツを指定します。

{
    "Time": "2012-01-15T10:45",
    "Props": {
        "EventName": "CustomEvent",
        "Revenue": 0.456
    }
}

次のデータ マッピングでは、 Props オブジェクト全体が動的列 Props にマップされますが、既にマップされている列は除外されます (Props.EventName は既に列 EventNameにマップされているため、除外されます)。

[
    { "Column": "Time", "Properties": { "Path": "$.Time" } },
    { "Column": "EventName", "Properties": { "Path": "$.Props.EventName" } },
    { "Column": "Props", "Properties": { "Path": "$.Props", "Transform":"DropMappedFields" } },
]

取り込まれたデータは次のようになります。

時刻 EventName prop
2012-01-15T10:45 CustomEvent {"Revenue": 0.456}

BytesAsBase64 変換

次の AVRO ファイルの内容を指定します。

{
    "Time": "2012-01-15T10:45",
    "Props": {
        "id": [227,131,34,92,28,91,65,72,134,138,9,133,51,45,104,52]
    }
}

次のデータ マッピングは、変換の有無に関係なく、ID 列を 2 回マップします。

[
    { "Column": "ID", "Properties": { "Path": "$.props.id" } },
    { "Column": "Base64EncodedId", "Properties": { "Path": "$.props.id", "Transform":"BytesAsBase64" } },
]

取り込まれたデータは次のようになります。

ID Base64EncodedId
[227,131,34,92,28,91,65,72,134,138,9,133,51,45,104,52] 44MiXBxbQUiGigmFMy1oNA==