CLI (v2) MLtable YAML スキーマ

[アーティクル]
09/01/2024

ソース JSON スキーマは、 https://azuremlschemas.azureedge.net/latest/MLTable.schema.jsonにあります。

Note

このドキュメントで詳しく説明されている YAML 構文は、最新バージョンの ML CLI v2 拡張機能の JSON スキーマに基づいています。この構文は、ML CLI v2 拡張機能の最新バージョンでのみ動作することが保証されています。以前のバージョンの拡張機能のスキーマについては、https://azuremlschemasprod.azureedge.net/ でご確認いただけます。

`MLTable` ファイルの作成方法

この記事では、 MLTable YAML スキーマについてのみ説明します。 MLTable の詳細については、次を参照してください。

MLTable ファイルの作成
MLTable artifacts creation
Pandas と Spark での消費
エンドツーエンドの例

「 Azure Machine Learning のテーブルを使用した作業を参照してください。

YAML 構文

キー	Type	説明	使用できる値	既定値
`$schema`	string	YAML スキーマ。 Azure Machine Learning Visual Studio Code 拡張機能を使用して YAML ファイルを作成する場合は、ファイルの先頭に `$schema` を含める場合は、スキーマとリソースの入力候補を呼び出すことができます。
`type`	const	`mltable` は、表形式データのスキーマ定義を抽象化します。データコンシューマーは、Pandas/Dask/Spark データフレームにテーブルをより簡単に具体化できます	`mltable`	`mltable`
`paths`	配列	パスには `file` パス、`folder` パス、またはパスの `pattern` を指定できます。 `pattern` では、ワイルドカード文字 (`*`、`?`、`[abc]`、`[a-z]`) を使用してファイル名のセットを指定する "グロビング" パターンがサポートされています。サポートされる URI の種類は `azureml`、`https`、`wasbs`、`abfss`、および `adl` です。 `azureml://` URI 形式の使用の詳細についてはCore yaml 構文に関するページを参照してください	`file` `folder` `pattern`
`transformations`	配列	定義されたパスから読み込まれたデータに適用される、定義された変換シーケンス。詳細については、 Transformations を参照してください。	`read_delimited` `read_parquet` `read_json_lines` `read_delta_lake` `take` `take_random_sample` `drop_columns` `keep_columns` `convert_column_types` `skip` `filter` `extract_columns_from_partition_format`

変換

読み取り変換

読み取り変換	説明	パラメーター
`read_delimited`	で指定された区切りテキストファイルを読み取る変換ステップを追加します。 `paths`	`infer_column_types`: 列のデータ型を推論するブール値。既定値は True です。型の推定を行うには、現在のコンピューティングからデータソースにアクセスできる必要があります。現在、型推論では最初の 200 行のみがプルされます。 `encoding`: ファイルエンコードを指定します。サポートされているエンコード: `utf8`、 `iso88591`、 `latin1`、 `ascii`、 `utf16`、 `utf32`、 `utf8bom`、および `windows1252`。既定のエンコードは `utf8` です。 `header`: ユーザーは、 `no_header`、 `from_first_file`、 `all_files_different_headers`、 `all_files_same_headers`のいずれかのオプションを選択できます。既定値は `all_files_same_headers` です。 `delimiter`: 列を分割する区切り記号。 `empty_as_string`: 空のフィールド値を空の文字列として読み込むかどうかを指定します。既定値 (False) は、空のフィールド値を null として読み取ります。この設定を True として渡すと空のフィールド値が空の文字列として読み取られます。数値または datetime データ型に変換された値の場合、空の値は null に変換されるため、この設定は無効です。 `include_path_column`: パス情報をテーブル内に列として保持するかどうかを示すブール値。既定値は False です。この設定は、複数のファイルを読み取るときに役立ち、特定のレコードの元のファイルを知りたい場合に役立ちます。ファイルパスに役立つ情報を保持することもできます。 `support_multi_line`: 既定では (`support_multi_line=False`)、引用符で囲まれたフィールド値の改行を含むすべての改行は、レコード区切りとして解釈されます。このデータ読み取り方法により速度が向上し、複数の CPU コアでの並列実行が最適化されます。ただし、フィールド値が正しく配置されていないレコードがサイレントで生成される可能性があります。区切りファイルに引用符で囲まれた改行が含まれていることがわかっている場合に、この値を `True` に設定します
`read_parquet`	で指定された Parquet 形式のファイルを読み取る変換ステップを追加します。 `paths`	`include_path_column`: パス情報をテーブル列として保持するブール値。既定値は False です。この設定は、複数のファイルを読み取り、特定のレコードの元のファイルを知りたい場合に役立ちます。ファイルパスに役立つ情報を保持することもできます。注: MLTable では、プリミティブ型で構成される列を持つ Parquet ファイルの読み取りのみがサポートされます。配列を含む列はサポートされていません
`read_delta_lake`	`paths` で指定された Delta Lake フォルダーを読み取る変換手順を追加します。特定のタイムスタンプまたはバージョンでデータを読み取ることができます	`timestamp_as_of`: 文字列。特定の Delta Lake データのタイムトラベルに指定するタイムスタンプ。特定の時点でデータを読み取る場合、datetime 文字列は RFC-3339/ISO-8601 形式である必要があります (例: "2022-10-01T00:00:00Z", "2022-10-01T00:00:00+08:00", "2022-10-01T01:30:00-08:00")。 `version_as_of`: 整数。特定の Delta Lake データのタイムトラベルに指定するバージョン。 `timestamp_as_of`の値を 1 つ指定する必要があります。`version_as_of`
`read_json_lines`	で指定された json ファイルを読み取る変換ステップを追加します `paths`	`include_path_column`: パス情報を MLTable 列として保持するかどうかを示すブール値。既定値は False です。この設定は、複数のファイルを読み取り、特定のレコードの元のファイルを知りたい場合に役立ちます。さらに、ファイルパスに有用な情報を保持できます。 `invalid_lines`: 無効な JSON を持つ行を処理する方法を決定します。サポートされる値は `error` と `drop` です。既定値は `error` です `encoding`: ファイルエンコードを指定します。サポートされているエンコード: `utf8`、 `iso88591`、 `latin1`、 `ascii`、 `utf16`、 `utf32`、 `utf8bom`、および `windows1252`。既定値は `utf8` です

その他の変換

変換	説明	パラメーター	例
`convert_column_types`	指定した列をそれぞれの指定された新しい型に変換する変換ステップを追加します	`columns` 変換する列名の配列 `column_type` 変換先の型 (`int`、 `float`、 `string`、 `boolean`、 `datetime`)	`- convert_column_types: - columns: [Age] column_type: int` Age 列を整数に変換します。 `- convert_column_types: - columns: date column_type: datetime: formats: - "%d/%m/%Y"` 日付列を形式 `dd/mm/yyyy`に変換します。 datetime 変換の詳細については、`to_datetime` を参照してください。 `- convert_column_types: - columns: [is_weekday] column_type: boolean: true_values:['yes', 'true', '1'] false_values:['no', 'false', '0']` is_weekday列をブール値に変換します。列の yes/true/1 の値は `True`にマップされ、列の値は `False`にマップされます。ブール型変換の詳細については、 `to_bool` を参照してください
`drop_columns`	データセットから特定の列を削除する変換ステップを追加します	削除する列名の配列	`- drop_columns: ["col1", "col2"]`
`keep_columns`	指定した列を保持する変換ステップを追加し、データセットから他のすべてを削除します	保持する列名の配列	`- keep_columns: ["col1", "col2"]`
`extract_columns_from_partition_format`	各パスのパーティション情報を使用し、指定したパーティション形式に基づいてそれらを列に抽出する変換手順を追加します。	使用するパーティション形式	`- extract_columns_from_partition_format: {column_name:yyyy/MM/dd/HH/mm/ss}` は datetime 列を作成します。ここで、'yyyy'、'MM'、'dd'、'HH'、'mm'、'ss' を使用して datetime 型の年、月、日、時、分、および 2 番目の値を抽出します
`filter`	データをフィルター処理して、指定された式に一致するレコードのみを残します。	文字列としての式	`- filter: 'col("temperature") > 32 and col("location") == "UK"'` 温度が32を超える行のみを残し、英国は場所です
`skip`	この MLTable の最初のカウント行をスキップする変換手順を追加します。	スキップする行数	`- skip: 10` 最初の 10 行がスキップされます
`take`	この MLTable の最初のカウント行を選択する変換手順を追加します。	取得するテーブルの先頭からの行数	`- take: 5` 最初の 5 行が取得されます。
`take_random_sample`	確率によってこの MLTable の各行をランダムに選択する変換手順を追加します。	`probability` 個々の行を選択する確率。 [0,1] の範囲内である必要があります。 `seed` オプションのランダムシード	`- take_random_sample: probability: 0.10 seed:123` 123 のランダムシードを使用して行の 10% のランダムサンプルを取得する

例

MLTable の使用例。その他の例については、以下を参照してください。

クイックスタート

このクイックスタートでは、パブリック https サーバーから有名な iris データセットを読み取ります。続行するには、 MLTable ファイルをフォルダーに配置する必要があります。最初に、次のフォルダーと MLTable ファイルを作成します。

mkdir ./iris
cd ./iris
touch ./MLTable

次に、このコンテンツを MLTable ファイルに配置します。

$schema: https://azuremlschemas.azureedge.net/latest/MLTable.schema.json

type: mltable
paths:
    - file: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv

transformations:
    - read_delimited:
        delimiter: ','
        header: all_files_same_headers
        include_path_column: true

その後、次の方法で Pandas に具体化できます。

重要

mltable Python SDK をインストールしておく必要があります。次のコマンドを使用して、この SDK をインストールします。

pip install mltable.

import mltable

tbl = mltable.load("./iris")
df = tbl.to_pandas_dataframe()

データに Path という名前の新しい列が含まれていることを確認します。この列には、 https://azuremlexamples.blob.core.windows.net/datasets/iris.csv データパスが含まれています。

CLI では、次のデータ資産を作成できます。

az ml data create --name iris-from-https --version 1 --type mltable --path ./iris

MLTableを含むフォルダーは、クラウドストレージ (既定の Azure Machine Learning データストア) に自動的にアップロードされます。

ヒント

Azure Machine Learning データ資産は、Web ブラウザーのブックマーク (お気に入り) に似ています。最も頻繁に使用されるデータを指す長い URI (ストレージパス) を記憶する代わりに、データ資産を作成し、フレンドリ名でその資産にアクセスできます。

区切りテキストファイル

$schema: https://azuremlschemas.azureedge.net/latest/MLTable.schema.json
type: mltable

# Supported paths include:
# local: ./<path>
# blob: wasbs://<container_name>@<account_name>.blob.core.windows.net/<path>
# Public http(s) server: https://<url>
# ADLS gen2: abfss://<file_system>@<account_name>.dfs.core.windows.net/<path>/
# Datastore: azureml://subscriptions/<subid>/resourcegroups/<rg>/workspaces/<ws>/datastores/<datastore_name>/paths/<path>

paths:
  - file: abfss://<file_system>@<account_name>.dfs.core.windows.net/<path>/ # a specific file on ADLS
  # additional options
  # - folder: ./<folder> a specific folder
  # - pattern: ./*.csv # glob all the csv files in a folder

transformations:
    - read_delimited:
        encoding: ascii
        header: all_files_same_headers
        delimiter: ","
        include_path_column: true
        empty_as_string: false
    - keep_columns: [col1, col2, col3, col4, col5, col6, col7]
    # or you can drop_columns...
    # - drop_columns: [col1, col2, col3, col4, col5, col6, col7]
    - convert_column_types:
        - columns: col1
          column_type: int
        - columns: col2
          column_type:
            datetime:
                formats:
                    - "%d/%m/%Y"
        - columns: [col1, col2, col3] 
          column_type:
            boolean:
                mismatch_as: error
                true_values: ["yes", "true", "1"]
                false_values: ["no", "false", "0"]
      - filter: 'col("col1") > 32 and col("col7") == "a_string"'
      # create a column called timestamp with the values extracted from the folder information
      - extract_columns_from_partition_format: {timestamp:yyyy/MM/dd}
      - skip: 10
      - take_random_sample:
          probability: 0.50
          seed: 1394
      # or you can take the first n records
      # - take: 200

Parquet

$schema: https://azuremlschemas.azureedge.net/latest/MLTable.schema.json
type: mltable

# Supported paths include:
# local: ./<path>
# blob: wasbs://<container_name>@<account_name>.blob.core.windows.net/<path>
# Public http(s) server: https://<url>
# ADLS gen2: abfss://<file_system>@<account_name>.dfs.core.windows.net/<path>/
# Datastore: azureml://subscriptions/<subid>/resourcegroups/<rg>/workspaces/<ws>/datastores/<datastore_name>/paths/<path>

paths:
  - pattern: azureml://subscriptions/<subid>/resourcegroups/<rg>/workspaces/<ws>/datastores/<datastore_name>/paths/<path>/*.parquet
  
transformations:
  - read_parquet:
        include_path_column: false
  - filter: 'col("temperature") > 32 and col("location") == "UK"'
  - skip: 1000 # skip first 1000 rows
  # create a column called timestamp with the values extracted from the folder information
  - extract_columns_from_partition_format: {timestamp:yyyy/MM/dd}

Delta Lake

$schema: https://azuremlschemas.azureedge.net/latest/MLTable.schema.json
type: mltable

# Supported paths include:
# local: ./<path>
# blob: wasbs://<container_name>@<account_name>.blob.core.windows.net/<path>
# Public http(s) server: https://<url>
# ADLS gen2: abfss://<file_system>@<account_name>.dfs.core.windows.net/<path>/
# Datastore: azureml://subscriptions/<subid>/resourcegroups/<rg>/workspaces/<ws>/datastores/<datastore_name>/paths/<path>

paths:
- folder: abfss://<file_system>@<account_name>.dfs.core.windows.net/<path>/

# NOTE: for read_delta_lake, you are *required* to provide either
# timestamp_as_of OR version_as_of.
# timestamp should be in RFC-3339/ISO-8601 format (for example:
# "2022-10-01T00:00:00Z", "2022-10-01T00:00:00+08:00",
# "2022-10-01T01:30:00-08:00")
# To get the latest, set the timestamp_as_of at a future point (for example: '2999-08-26T00:00:00Z')

transformations:
 - read_delta_lake:
      timestamp_as_of: '2022-08-26T00:00:00Z'
      # alternative:
      # version_as_of: 1

重要

制限事項: mltable は、Delta Lake からデータを読み取る際のパーティションキーの抽出はサポートしていません。 mltable 変換の extract_columns_from_partition_format は、mltable を介して Delta Lake データを読み取る際には機能しません。

JSON

$schema: https://azuremlschemas.azureedge.net/latest/MLTable.schema.json
paths:
  - file: ./order_invalid.jsonl
transformations:
  - read_json_lines:
        encoding: utf8
        invalid_lines: drop
        include_path_column: false

次の方法で共有

CLI (v2) MLtable YAML スキーマ

`MLTable` ファイルの作成方法

YAML 構文

変換

読み取り変換

その他の変換

例

クイックスタート

区切りテキストファイル

Parquet

Delta Lake

JSON

次の手順

フィードバック

その他のリソース

次の方法で共有

CLI (v2) MLtable YAML スキーマ

MLTable ファイルの作成方法

YAML 構文

変換

読み取り変換

その他の変換

例

クイックスタート

区切りテキスト ファイル

Parquet

Delta Lake

JSON

次の手順

フィードバック

その他のリソース

`MLTable` ファイルの作成方法

区切りテキストファイル