Databricks レイクハウス監視でカスタムメトリックを使用する

2025-05-09

このページでは、Databricks レイクハウス監視でカスタムメトリックを作成する方法について説明します。自動的に計算される分析とドリフトの統計に加えて、カスタムメトリックを作成できます。たとえば、ビジネスロジックの何らかの側面をキャプチャする加重平均を追跡したり、カスタムモデル品質スコアを使用したりできます。また、(ベースラインまたは以前の時間枠と比較して) プライマリテーブルの値の変更を追跡するカスタムドリフトメトリックを作成することもできます。

MonitorMetric API の使用方法の詳細については、API リファレンスを参照してください。

カスタムメトリックの種類

Databricks レイクハウス監視には、次の種類のカスタムメトリックが含まれています。

メトリックを集計します。これは、プライマリテーブルの列に基づいて計算されます。集計メトリックは、プロファイルメトリックテーブルに格納されます。
派生メトリック。これは、以前に計算された集計メトリックに基づいて計算され、プライマリテーブルのデータを直接使用しません。派生メトリックは、プロファイルメトリックテーブルに格納されます。
2 つの異なる時間枠から、またはプライマリテーブルとベースラインテーブルの間で、以前に計算された集計または派生メトリックを比較する誤差メトリック。誤差メトリックは、誤差メトリックテーブルに格納されます。

派生メトリックとドリフトメトリックを可能な限り使用すると、完全なプライマリテーブルに対する再計算が最小限に抑えられます。集計されたメトリクスのみがプライマリテーブルからデータにアクセスします。その後、派生メトリックとドリフトメトリックは、集計メトリック値から直接計算できます。

カスタムメトリックパラメーター

カスタムメトリックを定義するには、SQL 列式の Jinja テンプレートを作成します。このセクションの表では、メトリックを定義するパラメーターと、Jinja テンプレートで使用されるパラメーターについて説明します。

パラメーター	説明
`type`	`MonitorMetricType.CUSTOM_METRIC_TYPE_AGGREGATE`、`MonitorMetricType.CUSTOM_METRIC_TYPE_DERIVED`、または `MonitorMetricType.CUSTOM_METRIC_TYPE_DRIFT` のいずれか。
`name`	メトリックテーブル内のカスタムメトリックの列名。
`input_columns`	メトリックを計算する必要がある入力テーブル内の列名の一覧。計算で複数の列が使用されていることを示すには、 `:table`を使用します。この記事の例を参照してください。
`definition`	メトリックの計算方法を指定する SQL 式の Jinja テンプレート。「definition の作成」を参照してください。
`output_data_type`	JSON 文字列形式のメトリック出力の Spark データ型。

`definition` の作成

definition パラメーターは、Jinja テンプレートの形式の単一の文字列式でなければなりません。結合やサブクエリを含めることはできません。

次の表に、メトリックの計算方法を指定する SQL Jinja テンプレートの作成に使用できるパラメーターを示します。

パラメーター	説明
`{{input_column}}`	カスタムメトリックの計算に使用される列。
`{{prediction_col}}`	ML モデル予測を保持する列。 `InferenceLog` 分析と共に使用します。
`{{label_col}}`	MLモデルの正解ラベルを保持する列。 `InferenceLog` 分析と共に使用します。
`{{current_df}}`	前の時間枠と比較した変動の場合。前の時間枠のデータ。
`{{base_df}}`	基準テーブルと比較した誤差の場合。ベースラインデータ。

集計メトリックの例

次の例では、列内の値の 2 乗の平均を計算し、 f1 列と f2列に適用します。出力はプロファイルメトリックテーブルに新しい列として保存され、 f1 および f2列に対応する分析行に表示されます。該当する列名は、Jinja パラメーターの {{input_column}}に置き換えて使用します。

from databricks.sdk.service.catalog import MonitorMetric, MonitorMetricType
from pyspark.sql import types as T

MonitorMetric(
    type=MonitorMetricType.CUSTOM_METRIC_TYPE_AGGREGATE,
    name="squared_avg",
    input_columns=["f1", "f2"],
    definition="avg(`{{input_column}}`*`{{input_column}}`)",
    output_data_type=T.StructField("output", T.DoubleType()).json(),
)

次のコードでは、列 f1 と f2の差の平均を計算するカスタムメトリックを定義します。この例では、[":table"] パラメーターでinput_columnsを使用して、テーブルの複数の列が計算で使用されることを示します。

from databricks.sdk.service.catalog import MonitorMetric, MonitorMetricType
from pyspark.sql import types as T

MonitorMetric(
    type=MonitorMetricType.CUSTOM_METRIC_TYPE_AGGREGATE,
    name="avg_diff_f1_f2",
    input_columns=[":table"],
    definition="avg(f1 - f2)",
    output_data_type=T.StructField("output", T.DoubleType()).json(),
)

この例では、加重モデル品質スコアを計算します。 critical列がTrueである観測の場合、その行の予測値が実際の値と一致しない場合、より重いペナルティが割り当てられます。未加工の列 (prediction と label) で定義されているため、集計メトリックとして定義されます。 :table列は、このメトリックが複数の列から計算されることを示します。 {{prediction_col}}と{{label_col}}の Jinja パラメーターは、モニターの予測ラベル列とグラウンドトゥルースラベル列の名前に置き換えられます。

from databricks.sdk.service.catalog import MonitorMetric, MonitorMetricType
from pyspark.sql import types as T

MonitorMetric(
    type=MonitorMetricType.CUSTOM_METRIC_TYPE_AGGREGATE,
    name="weighted_error",
    input_columns=[":table"],
    definition="""avg(CASE
      WHEN {{prediction_col}} = {{label_col}} THEN 0
      WHEN {{prediction_col}} != {{label_col}} AND critical=TRUE THEN 2
      ELSE 1 END)""",
    output_data_type=T.StructField("output", T.DoubleType()).json(),
)

派生メトリックの例

次のコードでは、このセクションで前に定義した squared_avg メトリックの平方根を計算するカスタムメトリックを定義します。これは派生メトリックであるため、プライマリテーブルデータを参照せず、 squared_avg 集計メトリックの観点から定義されます。出力は、プロファイルメトリックテーブルに新しい列として保存されます。

from databricks.sdk.service.catalog import MonitorMetric, MonitorMetricType
from pyspark.sql import types as T

MonitorMetric(
    type=MonitorMetricType.CUSTOM_METRIC_TYPE_DERIVED,
    name="root_mean_square",
    input_columns=["f1", "f2"],
    definition="sqrt(squared_avg)",
    output_data_type=T.StructField("output", T.DoubleType()).json(),
)

ドリフトメトリックの例

次のコードでは、このセクションで前に定義した weighted_error メトリックの変化を追跡するドリフトメトリックを定義します。 {{current_df}}パラメーターと{{base_df}} パラメーターを使用すると、メトリックは現在のウィンドウと比較ウィンドウからweighted_error値を参照できます。比較ウィンドウには、ベースラインデータまたは前の時間枠のデータを指定できます。誤差メトリックは、誤差メトリックテーブルに保存されます。

from databricks.sdk.service.catalog import MonitorMetric, MonitorMetricType
from pyspark.sql import types as T

MonitorMetric(
    type=MonitorMetricType.CUSTOM_METRIC_TYPE_DRIFT,
    name="error_rate_delta",
    input_columns=[":table"],
    definition="{{current_df}}.weighted_error - {{base_df}}.weighted_error",
    output_data_type=T.StructField("output", T.DoubleType()).json(),
)

次の方法で共有

Databricks レイクハウス監視でカスタム メトリックを使用する

カスタム メトリックの種類

カスタム メトリック パラメーター

definition の作成