メトリック ビューの YAML 構文リファレンス

メトリック ビュー定義では、標準の YAML 構文を使用して、ソース、結合、フィールド、メジャー、フィルター、ウィンドウ メジャー、具体化を宣言します。 以降のセクションでは、それぞれの文法全体について説明します。

各機能の最小ランタイムおよび YAML 仕様バージョンの要件については、 メトリック ビュー機能の可用性に関するページを参照してください。

YAML 仕様の詳細については、 YAML 仕様 1.2.2 のドキュメントを参照してください。

メトリック ビュー エディターで YAML を編集する

このページで説明されている YAML は、メトリック ビュー エディターで直接作成および編集できます。 カタログ エクスプローラーでメトリック ビューを開き、 <> ボタンをクリックして定義を編集します。 代わりに自然言語の説明から YAML を生成するには、エディターから Genie Code を開きます。 エディターの完全なチュートリアルについては、「 メトリック ビューの作成」を参照してください。

最上位の YAML フィールド

メトリック ビューの YAML 定義には、次の最上位レベルのフィールドが含まれています。

情報源

source フィールドは、メトリック ビューのデータ ソースを指定します。 サポートされているソースには、テーブル、ビュー、メトリック ビュー、SQL クエリが含まれます。 構成可能性は、メトリック ビュー全体に適用されます。 メトリック ビューをソースとして使用する場合は、新しいメトリック ビューでそのフィールドとメジャーを参照できます。 コンポーザビリティを参照してください。

テーブルに似た資産ソース

3 部構成の名前を使用して、テーブルのような資産を参照します。

source: catalog.schema.source_table

SQL クエリ ソース

SQL クエリを使用するには、クエリ テキストを YAML に直接記述します。

source: SELECT * FROM samples.tpch.orders o
  LEFT JOIN samples.tpch.customer c
  ON o.o_custkey = c.c_custkey

パラメーター

parameters ブロックは、呼び出し元がメトリック ビューにテーブル値関数としてクエリを実行するときに渡す名前付き値を定義します。 パラメーター化されたメトリック ビューのクエリなど、パラメーターを使用するタイミングと方法については、「メトリック ビュー でパラメーターを使用する」を参照してください。

各パラメーター定義には、次のフィールドが含まれています。

次の例では、 discount パラメーターを定義し、メジャー式で参照します。

version: 1.1
source: main.default.sales

parameters:
  - name: discount
    data_type: double
    default: 0

fields:
  - name: product
    expr: product

measures:
  - name: discountedSales
    expr: SUM((1 - discount) * amount)

Filter

YAML 定義のフィルターは、メトリック ビューを参照するすべてのクエリに適用されます。 フィルターを SQL ブール式として書き込みます。

# Single condition filter
filter: o_orderdate > '2024-01-01'

# Multiple conditions with AND
filter: o_orderdate > '2024-01-01' AND o_orderstatus = 'F'

# Multiple conditions with OR
filter: o_orderpriority = '1-URGENT' OR o_orderpriority = '2-HIGH'

# Complex filter with IN clause
filter: o_orderstatus IN ('F', 'P') AND o_orderdate >= '2024-01-01'

# Filter with NOT
filter: o_orderstatus != 'O' AND o_totalprice > 1000.00

# Filter with LIKE pattern matching
filter: o_comment LIKE '%express%' AND o_orderdate > '2024-01-01'

Joins

メトリック ビューでの結合では、ファクト テーブルからディメンション テーブル (スター スキーマ) への直接結合と、正規化されたディメンション テーブル (スノーフレーク スキーマ) 間のマルチホップ結合の両方がサポートされます。 SELECT ステートメントを使用して SQL クエリに結合することもできます。 ソースとして SQL クエリを使用するを参照してください。

各結合定義には、次のフィールドが含まれています。

スター スキーマ結合

スター スキーマでは、 source はファクト テーブルであり、 LEFT OUTER JOINを使用して 1 つ以上のディメンション テーブルと結合します。 メトリック ビューは、選択した列に基づいて、特定のクエリに必要なファクト テーブルとディメンション テーブルを結合します。

ON句または USING 句を使用して結合列を指定します。

• ON 句: ブール式を使用して結合条件を定義します。
• USING 句: 親テーブルと結合テーブルの両方で同じ名前の列を一覧表示します。

結合は、多対一リレーションシップに従う必要があります。 多対多の場合、結合されたディメンション テーブルから最初に一致する行が選択されます。

version: 1.1
source: samples.tpch.lineitem

joins:
  - name: orders
    source: samples.tpch.orders
    on: source.l_orderkey = orders.o_orderkey

  - name: part
    source: samples.tpch.part
    on: source.l_partkey = part.p_partkey

fields:
  - name: Order Status
    expr: orders.o_orderstatus

  - name: Part Name
    expr: part.p_name

measures:
  - name: Total Revenue
    expr: SUM(l_extendedprice * (1 - l_discount))

  - name: Line Item Count
    expr: COUNT(1)

Snowflake スキーマ結合

スノーフレーク スキーマは、ディメンション テーブルを正規化してサブディメンションに接続することで、スター スキーマを拡張します。 これにより、複数レベルの結合構造が作成されます。 最小ランタイム要件については、 メトリック ビュー機能の可用性 に関する記事を参照してください。

スノーフレーク スキーマを定義するには、親結合定義内に joins を入れ子にします。

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    'on': o_custkey = c_custkey
    joins:
      - name: nation
        source: samples.tpch.nation
        'on': c_nationkey = n_nationkey

fields:
  - name: customer_nation
    expr: customer.nation.n_name

一対多結合

cardinality フィールドは、ソーステーブルと結合テーブルの間のリレーションシップを設定します。 既定の many_to_oneでは、結合されたテーブルがディメンション参照として扱われます。 結合テーブルをファクト ソースとして扱う cardinality: one_to_many 設定すると、エンジンはソース グレインで個別に集計されます。これにより、1 つのソース行が結合テーブル内の複数の行と一致します。 一対多結合には、Databricks Runtime 18.1 以降と YAML 仕様バージョン 1.1 が必要です。 メトリック ビュー機能の可用性に関する記事を参照してください。

一対多結合には、次の規則が適用されます。

• フィールドはソース行ごとに 1 つの値に解決する必要があるため、 fields 定義では 1 対多の列を使用できません。
• 1 つの集計関数は、1 つのソースの列を参照する必要があります。 count(orders.order_id) / count(*)など、個別の集計の結果に算術演算を適用できます。
• 一対多結合のすべての子孫も one_to_manyする必要があります。 最上位の兄弟結合では、カーディナリティを混在させることができます。
• orders.order_items.item_idなど、入れ子になった結合内の列を、結合名の完全なドット パスで参照します。

次の例では、注文メジャーが顧客の行を複製せずに集計されるように、ordersを使用してcustomers ソースにcardinality: one_to_manyを結合します。

version: 1.1
source: main.sales.customers

joins:
  - name: orders
    source: main.sales.orders
    on: orders.customer_id = source.customer_id
    cardinality: one_to_many

fields:
  - name: customer_name
    expr: customer_name

measures:
  - name: customer_count
    expr: count(*)
  - name: order_count
    expr: count(orders.order_id)
  - name: total_order_revenue
    expr: sum(orders.amount)

概念の詳細と入れ子になった結合と兄弟結合の例については、「 結合カーディナリティ」を参照してください。

で結合を最適化する rely

結合の rely フィールドを使用して、クエリの計画時にクエリ アナライザーが使用するリレーションシップに関する保証を宣言します。 これらの保証により、特に結合テーブルのフィールドがフィルターで参照されている場合に、エンジンはクエリをより効率的に計画し、スキャンされるデータを減らすことができます。

rely マップでは、次のフィールドがサポートされています。

次の例では、at_most_one_matchからordersへの多対一結合のcustomerを有効にします。 顧客属性でフィルター処理またはグループ化するクエリは、最もメリットがあります。

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    rely:
      at_most_one_match: true

fields:
  - name: Customer name
    expr: customer.c_name
  - name: Customer market segment
    expr: customer.c_mktsegment

measures:
  - name: Total revenue
    expr: SUM(o_totalprice)

フィールド

フィールドは、クエリ時に SELECT、 WHERE、および GROUP BY 句で使用されるメトリック ビュー列です。 各式はスカラー値を返さなければなりません。 フィールドは、メトリック ビューのソース データまたは以前に定義されたフィールドの列を参照できます。

フィールドには、次のいずれかを指定できます。

• カテゴリ列またはグループ化列 (地域、状態、部署など)。
• 年齢、価格、数量など、集計されていない数値列。 数値フィールドは、 SUM や AVGなどの SQL 関数を使用してクエリ時に集計できます。

各フィールド定義には、次のプロパティが含まれています。

Example:

fields:
  # Basic field
  - name: order_date
    expr: o_orderdate
    comment: 'Date the order was placed'
    display_name: 'Order Date'

  # Field with SQL expression
  - name: order_month
    expr: DATE_TRUNC('MONTH', o_orderdate)
    display_name: 'Order Month'

  # Field with synonyms
  - name: order_status
    expr: CASE
      WHEN o_orderstatus = 'O' THEN 'Open'
      WHEN o_orderstatus = 'P' THEN 'Processing'
      WHEN o_orderstatus = 'F' THEN 'Fulfilled'
      END
    display_name: 'Order Status'
    synonyms: ['status', 'fulfillment status']

対策

測定基準は、事前に決定された集計レベルなしで結果を生成する式です。 集計関数を使用して表現する必要があります。 クエリでメジャーを参照するには、 MEASURE 関数を使用します。 メジャーは、ソース データ内のベース列、前に定義されたフィールド、または前に定義されたメジャーを参照できます。

各メジャー定義には、次のフィールドが含まれています。

集計関数の一覧については、集計関数を参照してください。

Example:

measures:
  # Simple count measure
  - name: order_count
    expr: COUNT(1)
    display_name: 'Order Count'

  # Sum aggregation measure with synonyms
  - name: total_revenue
    expr: SUM(o_totalprice)
    comment: 'Gross revenue from all orders'
    display_name: 'Total Revenue'
    synonyms: ['revenue', 'total sales']

  # Distinct count measure
  - name: unique_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: 'Unique Customers'

  # Calculated measure combining multiple aggregations
  - name: avg_order_value
    expr: SUM(o_totalprice) / COUNT(DISTINCT o_orderkey)
    display_name: 'Avg Order Value'
    synonyms: ['AOV', 'average order']

  # Filtered measure with WHERE condition
  - name: open_order_revenue
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'O')
    display_name: 'Open Order Revenue'
    synonyms: ['backlog', 'outstanding revenue']

ワイルドカードを使用してフィールドとメジャーを一括インポートする

適用対象: YAML 仕様 1.1 を使用した Databricks Runtime 18.2 以降

fieldsまたはmeasures定義では、* フィールドのワイルドカード (expr) を使用して、ソースまたは結合されたテーブルから各列を一覧表示せずにすべての列をインポートできます。 これは、標準ビューの SELECT * と同様に、メトリック ビューでアップストリームアセットのすべての列を公開する場合に便利です。 Azure Databricksメトリック ビューを作成または置換するときにワイルドカードを具象列に展開し、ソース列名から各列名を派生させます。

明示的な列定義と同様に、メトリック ビューを作成するとワイルドカード式が展開されます。 後でソースに追加された列を取得するには、 CREATE OR REPLACE または ALTERを使用してメトリック ビューを再作成します。

ワイルドカードでは、次の形式がサポートされます。

ワイルドカード式には、次の規則が適用されます。

• name フィールドを省略します。 Azure Databricksはソースから列名を派生させます。そのため、ワイルドカード式ではnameは使用できません。
• ワイルドカード式ではセマンティック メタデータは使用できません。 ワイルドカードに comment、 display_name、 format、または synonyms を設定しないでください。 特定の列にメタデータを追加するには、 EXCEPT を使用してワイルドカードから除外し、明示的に定義します。
• measures定義では、ワイルドカードはメトリック ビュー ソースからのみメジャーをインポートします。 ベース テーブルにはメジャーがないため、ソースがベース テーブルの場合、ワイルドカードはメジャーに展開されません。
• ワイルドカードインポートされた列は、後の fields または measures 式の派生名で参照することはできません。 代わりに、完全なパスを使用してソース列を参照します。

名前の競合を解決する

ワイルドカードを使用して複数のソースから列をインポートすると、名前を共有する列 ( id や dateなど) が競合し、定義を保存するときにエラーが発生します。 競合を解決するには、 EXCEPTを含む各ワイルドカードから列を除外し、一意の名前で明示的に定義します。

fields:
  - expr: source.* EXCEPT (id)
  - expr: customer.* EXCEPT (id)
  - name: source_id
    expr: source.id
  - name: customer_id
    expr: customer.id

ワイルドカードの例

次の定義では、ソースと結合テーブルからすべての列をインポートし、2 つの列を除外し、メタデータを追加するために 1 つの列を明示的に定義します。

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    joins:
      - name: nation
        source: samples.tpch.nation
        on: customer.c_nationkey = nation.n_nationkey

fields:
  # Import all columns from the source
  - expr: source.*

  # Import all columns from a joined table, excluding two
  - expr: customer.nation.* EXCEPT (n_name, n_comment)

  # Define a specific column explicitly to add metadata
  - name: nation_name
    expr: customer.nation.n_name
    comment: "Customer's nation"
    display_name: 'Nation Name'

ウィンドウ メジャー

window フィールドは、メジャーのウィンドウ集計、累積集計、または準加法集計を定義します。 ウィンドウ メジャーとユース ケースの詳細については、「 ウィンドウ メジャー」を参照してください。

各ウィンドウの仕様には、次のフィールドが含まれています。

(1) 参照されるフィールドは決定論的である必要があります。 rand()、uuid()、current_timestamp()などの非決定論的な式では、予期しないウィンドウ順序が生成され、集計結果が正しくない可能性があります。

サポートされている range 値

• current: ウィンドウ順序の値がアンカー行の値と等しい行。
• cumulative: ウィンドウ順序の値がアンカー行の値以下であるすべての行。
• trailing <value> <unit> [inclusive | exclusive]: アンカー行の行が、指定した時間単位 (たとえば、 trailing 7 day) で後方に移動します。 省略可能な inclusive または exclusive 修飾子には、Databricks Runtime 18.1 および YAML 仕様バージョン 1.1 以降が必要であり、アンカー行をウィンドウに含めるかどうかを制御します。 既定値は exclusive です。 アンカー行を含めるまたは除外するを参照してください。
• leading <value> <unit> [inclusive | exclusive]: アンカー行の行 (たとえば、 leading 3 monthなど)、指定した時間単位で進みます。 省略可能な inclusive または exclusive 修飾子には、Databricks Runtime 18.1 および YAML 仕様バージョン 1.1 以降が必要であり、アンカー行をウィンドウに含めるかどうかを制御します。 既定値は exclusive です。 アンカー行を含めるまたは除外するを参照してください。
• all: ウィンドウの順序の値に関係なく、すべての行。

ウィンドウ メジャーの例

次の例では、一意の顧客のローリング 7 日間のカウントを計算します。

version: 1.1
source: samples.tpch.orders

fields:
  - name: order_date
    expr: o_orderdate

measures:
  - name: rolling_7day_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: '7-Day Rolling Customers'
    window:
      - order: order_date
        range: trailing 7 day
        semiadditive: last

パラメータとしてウィンドウサイズを渡します

数値を trailing や leadingrange 、あるいは offsetにハードコーディングする代わりに、 パラメータを参照できるようになり、呼び出し元がメトリクスビューを問い合わせる際にウィンドウサイズを渡すことができます。 これにはDatabricks Runtime 18.2以上のSQLウェアハウスやその他の計算リソースが必要です。

ウィンドウサイズとして使われるパラメータには以下のルールが適用されます。

• パラメータの data_type は int、 smallint、 bigintなど整数でなければなりません。
• 値は単純なパラメータ名でなければならず、式ではありません。 たとえば、trailing window_size dayではなく trailing window_size + 1 dayを使用します。 また、-window_sizeのoffsetのようにパラメータ名の前に記号を書くこともできません。 負のオフセットを通すには、符号をパラメータの内側に入れます。
• パラメータは、範囲型(trailing、 leading)、ピリオド(day、 month、 year)、包括性キーワード(inclusive、 exclusive)、 offsetなどのウィンドウキーワード名を付けられることはできません。
• ユニットは文字通りのままです。 数値の大きさのみをパラメータ化でき、周期は設定できません。

以下の例は window_size パラメータを定義し、 trailing の範囲で参照しているため、各発信者はローリングウィンドウの日数を選択できます。

version: 1.1
source: samples.tpch.orders

parameters:
  - name: window_size
    data_type: int
    default: 7

fields:
  - name: order_date
    expr: o_orderdate

measures:
  - name: rolling_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: 'Rolling Customers'
    window:
      - order: order_date
        range: trailing window_size day
        semiadditive: last

パラメータを定義するメトリックビューをクエリするには、「 パラメータ付きメトリックビューをクエリ」を参照してください。

具体化

materialization フィールドは、具体化されたビューを使用して自動クエリ アクセラレーションを構成します。 具体化のしくみ、要件、ベスト プラクティスの詳細については、 メトリック ビューの具体化を参照してください。

materialization フィールドには、次の最上位レベルのフィールドが含まれています。

materialized_viewsの各エントリには、次のフィールドがあります。

具体化の例

次の例では、複数の具体化を使用してメトリック ビューを定義します。

version: 1.1
source: prod.operations.orders_enriched_view
filter: revenue > 0
# filter, fields, and measures can't use invoker-dependent expressions: no current_user(), is_member(), etc.
# source can't have RLS, column masking, or ABAC policies

joins:
  - name: customers
    source: prod.operations.customers
    on: source.customer_id = customers.id
    # if one-to-many, all materializations below drop to exact match only

fields:
  - name: category
    expr: substring(category, 5)
  - name: order_date
    expr: order_date

measures:
  - name: total_revenue
    expr: SUM(revenue)

  - name: number_of_suppliers
    expr: COUNT(DISTINCT supplier_id)

  - name: revenue_for_open_orders
    expr: SUM(revenue) FILTER (WHERE status = 'O')

  - name: blended_margin
    expr: SUM(revenue) - SUM(cost)

  - name: rolling_7day_customers
    expr: COUNT(DISTINCT customer_id)
    window:
      - order: order_date
        range: trailing 7 day
        semiadditive: last

materialization:
  schedule: every 6 hours
  mode: relaxed

  materialized_views:
    - name: baseline
      type: unaggregated
      # only one allowed per metric view; doesn't use dimensions or measures keys
      # no benefit if source is an unfiltered direct table reference

    - name: daily_status_metrics
      type: aggregated
      dimensions:
        - order_date
        - category # avoid overly granular dimensions, such as millisecond timestamps
      measures:
        - total_revenue # rollup-eligible
        - number_of_suppliers # exact match only (non-additive)
        - revenue_for_open_orders # rollup-eligible (deterministic filter)
        - blended_margin # exact match only (multiple aggregates)
        - rolling_7day_customers # exact match only (window measure)
      cluster_by:
        cols:
          - order_date
          - category
      partition_by:
        - order_date

列名の参照

YAML 式でスペースまたは特殊文字を含む列名を参照する場合は、列名をバックティックで囲みます。 式がバックティックで始まり、YAML 値として直接使用される場合は、式全体を二重引用符で囲みます。 有効なYAMLの値はバックティックで始めることができません。

書式設定の例

次の例を使用して、一般的なシナリオで YAML を正しく書式設定する方法について説明します。

列名を参照する

次の例では、含まれる文字に応じて列参照の書式を設定する方法を示します。

スペースは使用できません

ソース列: revenue

expr: "revenue"
expr: 'revenue'
expr: revenue

列名の前後には二重引用符、一重引用符、または引用符を使用しません。

スペースを含む列名

ソース列: `First Name`

expr: '`First Name`'

スペースをエスケープするためにバックティックを使用します。 式全体を二重引用符で囲みます。

SQL 式にスペースを含む列名

ソース列: `First Name`、 `Last Name`

expr: CONCAT(`First Name`, ' ', `Last Name`)

式がバッククォートで始まらない場合は、二重引用符は必要ありません。

引用符を含む列名

ソース列: "name"

expr: '`"name"`'

列名の二重引用符をエスケープするには、バッククォートを使用します。 式を一重引用符で囲みます。

コロンを含む式

expr: "CASE WHEN `Customer Tier` = 'Enterprise: Premium' THEN 1 ELSE 0 END"

複数行式

expr: |
  CASE WHEN
    revenue > 100 THEN 'High'
  ELSE 'Low'
  END

YAML 1.1 へのアップグレード

コメントは以前のバージョンとは異なる方法で処理されるため、メトリック ビューを YAML 仕様バージョン 1.1 にアップグレードするには注意が必要です。

コメントの種類

• YAML コメント (#): YAML ファイルに直接書き込まれたインラインまたは 1 行のコメント。
• Unity カタログのコメント: メトリック ビューまたはその列の Unity カタログに格納されているコメント。 これらは YAML コメントとは別です。

アップグレードに関する考慮事項

メトリック ビューでのコメントの処理方法に一致するアップグレード パスを選択します。

オプション 1: ノートブックまたは SQL エディターを使用して YAML コメントを保持する

メトリック ビューに保持する YAML コメント (#) が含まれている場合は、次の手順を使用します。

1. ノートブックまたは SQL エディターで ALTER VIEW コマンドを使用します。
2. $$..$$した後、元の YAML 定義を AS セクションにコピーします。 version の値を 1.1 に変更します。
3. メトリック ビューを保存します。

ALTER VIEW metric_view_name AS
$$
# The notebook preserves inline comments
version: 1.1
source: samples.tpch.orders
fields:
- name: order_date # The notebook preserves inline comments
  expr: o_orderdate
measures:
# The notebook preserves commented out definitions
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

オプション 2: Unity カタログのコメントを保持する

1. YAML 定義内の適切な comment フィールドにすべての Unity カタログ コメントをコピーします。 version の値を 1.1 に変更します。
2. メトリック ビューを保存します。

ALTER VIEW metric_view_name AS
$$
version: 1.1
source: samples.tpch.orders
comment: "Metric view of order (Updated comment)"

fields:
- name: order_date
  expr: o_orderdate
  comment: "Date of order - Copied from Unity Catalog"

measures:
- name: total_revenue
  expr: SUM(o_totalprice)
  comment: "Total revenue"
$$

YAML 仕様のバージョン履歴と各機能の最小ランタイム要件については、 メトリック ビューの機能の可用性に関するページを参照してください。