最新の Unity カタログ テーブル形式にトレースを移行する

スキーマにリンクされた形式 () を使用してベータ リリース中に catalog.schema場合は、パブリック プレビュー リリースで導入されたテーブル プレフィックス形式 (catalog.schema.table_prefix) にそれらのトレースを移行できます。

Databricks では、新規および既存のすべての UC トレース ワークロードに対して、テーブル プレフィックス形式をお勧めします。 より高速な時間範囲クエリ、豊富な属性の種類、専用の注釈テーブル、スキーマごとの複数のトレース宛先のサポートが提供されます。

移行では、Spark SQL を使用してスパンと注釈 (タグ、評価、メタデータ) がコピーされます。

以前の形式を使用する実験を特定する

Unity カタログにトレースを格納する実験では、次の 2 つの形式のいずれかを使用します。

  • スキーマリンク (ベータ リリース中に使用): 実験のトレース先は 2 部構成のパス (catalog.schema)。 トレース データは、 mlflow_experiment_trace_otel_spans や mlflow_experiment_trace_otel_logsなどの固定名テーブルに格納されます。 タグ、評価、およびメタデータは、ログ テーブルにログ イベントとして格納されます。
  • テーブル プレフィックス (パブリック プレビュー リリース以降で使用): 実験のトレース先は、3 部構成のパス (catalog.schema.table_prefix) です。 トレース データは、 <table_prefix>_otel_spansなどのプレフィックス名前空間のテーブルに格納され、注釈には専用のテーブルがあります。

Unity カタログ スキーマに mlflow_experiment_trace_otel_spans および mlflow_experiment_trace_otel_logs という名前のテーブルが含まれている場合、実験では以前のスキーマにリンクされた形式が使用され、移行の対象となります。

前提条件

  • Unity カタログ対応ワークスペース。

  • Databricks Runtime 15.3 以降を実行しているAzure Databricks クラスター。

  • databricks-agents Python パッケージ:

    pip install "databricks-agents>=1.10.0"

  • 次のアクセス許可:

    • USE_CATALOGとUSE_SCHEMAソースのカタログとスキーマ。
    • USE_CATALOG、USE_SCHEMA、およびMODIFYは宛先カタログとスキーマに対してです。

手順 1: ターゲット実験を作成する

Unity カタログのテーブル プレフィックスの場所にリンクされた実験を作成します。 移行されたトレースはここに格納されます。 完全なセットアップの詳細については、「 セットアップ: Unity カタログトレースの場所を使用して実験を作成する」を参照してください。

import mlflow
from mlflow.entities.trace_location import UnityCatalog

experiment = mlflow.set_experiment(
    experiment_name="/Workspace/Users/<user>/<experiment_name>",
    trace_location=UnityCatalog(
        catalog_name="<destination_catalog>",
        schema_name="<destination_schema>",
        table_prefix="<table_prefix>",
    ),
)

print(f"Experiment ID: {experiment.experiment_id}")

実験 ID を保存します。 これを使用して、新しい宛先にトレースを記録するようにノートブック、ジョブ、またはデプロイされたモデルを構成します。

手順 2: トレース ログを切り替えてソース実験への書き込みを停止する

ノートブック、ジョブ、またはデプロイされたモデルを更新して、手順 1 で作成した新しい実験にトレースを記録します。 これにより、新しいトレースが宛先テーブルに直接移動します。

Important

移行を実行する前に、ソース実験へのすべての書き込みを停止します。 移行中にソース テーブルに書き込まれたトレースはコピーされない可能性があります。 ノートブック、ジョブ、またはデプロイされたモデルがソース実験に対してトレースをアクティブに記録していないことを確認します。

最初にドライ ランを実行する場合は、この手順をスキップして、運用環境のワークロードを切り替えずに移行を実行できます。

手順 3: 移行を実行する

クラスター上のAzure Databricks ノートブックで、次のコマンドを実行します。

from databricks.migrations.v1_to_v2 import V1ToV2SqlMigration

migration = V1ToV2SqlMigration(
    v1_source_schema="<source_catalog>.<source_schema>",
    v2_destination_prefix="<destination_catalog>.<destination_schema>.<table_prefix>",
)
migration.run()

プレースホルダーを置き換えてください。

  • <source_catalog>.<source_schema>: ソース トレース テーブルが格納されている Unity カタログ カタログとスキーマ。
  • <destination_catalog>.<destination_schema>.<table_prefix>: 宛先の Unity Catalog のカタログ、スキーマ、テーブルのプレフィックス。 これは、手順 1 で構成した場所と一致する必要があります。

移行は何度行っても結果が変わらない性質を持っています。 途中で失敗した場合 (クラスターのタイムアウトなど)、安全に再実行できます。 既に移行された行は自動的にスキップされます。

移行が完了すると、新しい移行先の実験でトレースを使用できるようになります。 ソース テーブルは移行によって変更されず、バックアップとして保持できます。

  • Last updated on