メトリクスビュー YAML 構文リファレンス
メトリクスビューの定義では、標準のYAML構文を使用して、ソース、結合、フィールド、メジャー、フィルター、ウィンドウメジャー、マテリアライゼーションを宣言します。次のセクションでは、それぞれの完全な文法について説明します。
各機能の最小ランタイムと YAML 仕様のバージョン要件については、メトリクスビューの機能の可用性 を参照してください。
YAML仕様について詳しく学ぶには、YAML Specification 1.2.2ドキュメントを参照してください。
メトリクスビューエディタでYAMLを編集
このページに記述されているYAMLは、メトリクスビューエディターで直接記述および編集できます。カタログエクスプローラーでメトリクスビューを開き、<>ボタンをクリックして定義を編集します。代わりに自然言語記述からYAMLを生成するには、エディターからGenie Codeを開きます。完全なエディターウォークスルーについては、メトリクスビューの作成を参照してください。
最上位のYAMLフィールド
メトリクスビューのYAML定義には、以下のトップレベルフィールドが含まれます：
フィールド | Type | 説明 |
|---|---|---|
| String | 必須。定義が使用するメトリクスビューのYAML仕様のバージョン（例: |
| String | オプション。メトリクスビューの説明。 |
| String | 必須。メトリクスビューのソースデータです。メトリクスビューやSQLクエリーなど、テーブルのようなUnity Catalogアセットのいずれでも構いません。See ソース. |
| Array | オプション。呼び出し元がメトリクスビューをテーブル値関数としてクエリーするときに渡す名前付きの値。See パラメーター. |
| String | オプション。すべてのクエリーに適用される SQL Boolean 式。「フィルター」を参照してください。 |
| Array | オプション。スター スキーマとスノーフレーク スキーマの結合。「結合」を参照してください。 |
| Array | 条件です。名前、式、オプションのセマンティックメタデータを含むフィールド定義。 |
| Array | 条件です。名前、集計式、およびオプションのセマンティックメタデータを含むメジャー定義。 |
| オブジェクト | オプションです。マテリアライズドビューを使用したクエリーを高速化するための構成です。更新スケジュールとマテリアライズドビューの定義が含まれます。マテリアライゼーションを参照してください。 |
ソース
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
SQLクエリーをJOIN句を持つソースとして使用する場合、基になるテーブルに主キー制約と外部キー制約を設定し、最適なクエリーパフォーマンスのためにRELYオプションを使用してください。詳細については、主キー、外部キー、および一意制約の宣言と主キーと一意制約を使用したクエリーの最適化を参照してください。
パラメーター
parameters ブロックは、呼び出し元がテーブル値関数としてメトリクスビューをクエリーする際に渡す名前付き値を定義します。パラメーター化されたメトリクスビューのクエリーを含め、パラメーターを使用する時期と方法については、メトリクスビューでパラメーターを使用するを参照してください。
各パラメーター定義には、次のフィールドが含まれます：
フィールド | Type | 説明 |
|---|---|---|
| String | 必須。パラメーター名。フィールドとメジャーの式でこの名前でパラメーターを参照し、メトリクスビューをクエリーする際に名前付き引数として渡します。 |
| String | 必須。パラメーターの SQL データ型。 |
| 異なります。 | オプション。呼び出し元がパラメーターを渡さない場合に使用される値です。defaultは |
次の例では、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)
フィルター
YAML定義のフィルターは、メトリクスビューを参照するすべてのクエリーに適用されます。フィルターをSQL Boolean式として記述します。
# 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'
結合
メトリクスビューでの結合は、ファクトテーブルからディメンションテーブルへの直接結合（スタースキーマ）と、正規化されたディメンションテーブル間のマルチホップ結合（スノーフレークスキーマ）の両方をサポートしています。SELECTステートメントを使用して、SQLクエリーに結合することもできます。SQLクエリーをソースとして使用するを参照してください。
結合されたテーブルには、MAP 型の列を含めることはできません。MAP 型の列から値をアンパックするには、「マップまたは配列からネストされた要素を分解する」を参照してください。
各結合定義には、次のフィールドが含まれます。
フィールド | Type | 説明 |
|---|---|---|
| String | 必須。結合テーブルまたはSQLクエリーのエイリアス。フィールドまたはメジャーで結合テーブルの列を参照するときは、このエイリアスを使用してください。 |
| String | 必須。結合するテーブルの3部構成の名前です。SQLクエリーにすることもできます。 |
| String | 条件です。結合条件を定義するBoolean式。 |
| Array | 条件です。親テーブルと結合されたテーブルの両方に存在する列名のリスト。 |
| String | オプション。defaultは |
| Array | オプション。スノーフレークスキーマのモデリング用の入れ子になった結合定義のリスト。最小ランタイム要件については、メトリクスビューの機能の可用性を参照してください。 |
| Map | オプション。アナライザーが、より効率的なクエリープランを生成するために信頼できる結合に関する約束。「 |
スタースキーマ結合
スタースキーマでは、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)
source 名前空間はメトリックビューのソースから列を参照します。一方、結合の name はその結合されたテーブルから列を参照します。たとえば、source.l_orderkey = orders.o_orderkeyでは、sourceがlineitemを、ordersが結合されたテーブルを指します。on句でプレフィックスが指定されていない場合、参照はdefaultで結合されたテーブルになります。
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フィールドは、ソースと結合テーブル間の関係を設定します。The default, many_to_one, treats the joined table as a dimension lookup.cardinality: one_to_manyを設定して、結合テーブルを、エンジンがソース粒度で独立して集計するファクトソースとして扱います。これにより、単一のソース行が結合テーブル内の複数の行に一致するようになります。一対多結合には、Databricks Runtime 18.1以上とYAML仕様バージョン1.1が必要です。「メトリクスビュー機能の可用性」を参照してください。
1対多の結合に次のルールが適用されます。
- 1対多の列は
fields定義では使用できません。フィールドはソース行ごとに単一の値に解決される必要があるためです。 - 単一の集計関数は、1つのソースから列を参照する必要があります。個別の集計の結果に算術を適用できます（
count(orders.order_id) / count(*)など）。 - 1対多の結合のすべての子孫も
one_to_manyである必要があります。トップレベルの兄弟結合では、カーディナリティを混在させることができます。 - 結合名全体を介した完全なドットパスで、ネストされた結合の列を参照します。たとえば、
orders.order_items.item_idです。
次の例では、顧客の行を重複させることなく、注文メジャーが集計されるように、ordersをcardinality: one_to_manyでcustomersソースに結合します。
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マップでは、次のフィールドがサポートされています。
フィールド | Type | 説明 |
|---|---|---|
| Boolean | オプション。defaultは |
結合が多対一の場合にのみ at_most_one_match: true を設定します。このリレーションシップはランタイム時に検証されません。結合されたテーブルの複数の行が単一のソース行に一致する場合、メジャー（SUMやCOUNTなど）は正しくない結果を返します。
次の例では、ordersからcustomerへの多対一の結合でat_most_one_matchを有効にします。顧客の属性でフィルターまたはグループ化するクエリーが最も効果的です:
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)
フィールド
fields とdimensionsは、メトリクスビュー定義で同等のキーワードです。fieldsは推奨される用語であり、このドキュメント全体で使用されています。Catalog Explorerのローコードエディターはこれらの列を フィールド とラベル付けしますが、生成されるYAMLではdimensionsキーワードを使用します。dimensionsを使用する既存のメトリクスビューは引き続き機能し、新しい定義または更新された定義では両方のキーワードが受け入れられます。
フィールドは、クエリー時にSELECT、WHERE、およびGROUP BY句で使用されるメトリクスビューの列です。各式はスカラー値を返す必要があります。フィールドは、ソースデータからの列、またはメトリクスビューで以前に定義されたフィールドを参照できます。
フィールドは次のいずれかです：
- リージョン、ステータス、部署などのカテゴリ列またはグループ化列です。
- 未集計の数値列（例：年齢、価格、数量）。数値フィールドは、クエリー時に
SUMやAVGなどのSQL関数を使用して集計できます。
各フィールド定義には次のプロパティが含まれます:
属性 | Type | 説明 |
|---|---|---|
| String | 明示的な列式に必要です。フィールドの列エイリアス。Databricksがソースから名前を派生させるワイルドカード式の場合は、これを省略してください。ワイルドカードを使用したフィールドとメジャーの一括インポートを参照してください。 |
| String | 必須。ソースデータまたは以前に定義されたフィールドから列を参照できるSQL式。ソースまたは結合されたテーブルからすべての列をインポートするためのワイルドカードにすることができます。ワイルドカードを使用したフィールドとメジャーの一括インポートを参照してください。 |
| String | オプションです。フィールドの説明です。Unity Catalogとドキュメンテーションツールに表示されます。 |
| String | オプション。ビジュアライゼーションツールに表示されるラベル。255文字までです。YAML仕様1.1が必要です。メトリクス ビューの機能の可用性を参照してください。 |
| Map | オプションです。値の表示方法の書式指定。YAML仕様1.1が必要です。書式指定を参照してください。 |
| Array | オプション。AIおよびBIツールがフィールドを発見するための代替名。最大10個の同義語。それぞれ255文字に制限されます。YAML仕様1.1が必要です。同義語をご覧ください。 |
文字列のようなメトリクスビューフィールドは、ソース列がCHARまたはVARCHARの場合でも、常にSTRINGです。CHAR(n)のスペースパディングが失われるため、比較で異なる結果が返される可能性があります。例えば、column = 'COLLEGE'はソーステーブル（スペースで埋め込まれている）のCHAR(10)値とは一致しますが、メトリクスビューフィールドでは一致しません。
例：
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関数を使用します。メジャーは、ソースデータ内のベース列、以前に定義されたフィールド、または以前に定義されたメジャーを参照できます。
各メトリクス定義には次のフィールドが含まれます：
フィールド | Type | 説明 |
|---|---|---|
| String | 明示的なメジャー式に必要です。メジャーのエイリアス。Databricksがソースから名前を派生させるワイルドカード式の場合は、これを省略してください。ワイルドカードを使用したフィールドとメジャーの一括インポートを参照してください。 |
| String | 必須。1つ以上の集計関数を含むSQL式です。メトリクスビューソースからすべてのメジャーをインポートするためのワイルドカードにすることができます。ワイルドカードを使用したフィールドとメジャーの一括インポートを参照してください。 |
| String | オプション。メジャーの説明。Unity Catalogとドキュメンテーションツールに表示されます。 |
| String | オプション。ビジュアライゼーションツールに表示されるラベル。255文字までです。YAML仕様1.1が必要です。メトリクス ビューの機能の可用性を参照してください。 |
| Map | オプションです。値の表示方法の書式指定。YAML仕様1.1が必要です。書式指定を参照してください。 |
| Array | オプション。メジャーを検出するためのAIおよびBIツールの代替名。最大10個の同義語。それぞれ255文字に制限されます。YAML仕様1.1が必要です。メトリクス ビューの機能の可用性を参照してください。 |
| Array | オプション。ウィンドウ、累積、または半加法集計のウィンドウ指定。指定されていない場合、メジャーは標準の集計として動作します。「ウィンドウメジャー」を参照してください。 |
集計関数の一覧については、「集計関数」を参照してください。
例：
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']
ワイルドカードを使用してフィールドとメジャーを一括インポート
適用対象: Databricks Runtime 18.2以降（YAML仕様1.1の場合）
fields または measures の定義では、expr フィールドでワイルドカード (*) を使用して、ソースまたは結合テーブルからすべての列を個別に一覧表示せずにインポートできます。これは、標準ビューの SELECT * と同様に、メトリクス ビューで上流アセットのすべての列を公開したい場合に役立ちます。Databricks は、メトリクス ビューを作成または置換するときにワイルドカードを具体的な列に展開し、各列名をソース列名から派生させます。
明示的な列定義と同様に、メトリクスビューを作成するときにワイルドカード式が展開されます。後からソースに追加された列を取得するには、CREATE OR REPLACEまたはALTERを使用してメトリクスビューを再作成します。
ワイルドカードは次の形式をサポートしています。
構文 | 説明 |
|---|---|
| メトリクスビューソースからすべての列をインポートします。 |
| 結合名で参照される結合されたテーブルから、すべての列をインポートします。ネストされた結合では、 |
| リストにないものを除いて、ターゲットからすべての列をインポートします。 |
|
|
ワイルドカード式には次のルールが適用されます:
nameフィールドを省略します。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フィールドは、メジャーのウィンドウ、累積、または半加法集計を定義します。ウィンドウメジャーとユースケースの詳細については、ウィンドウメジャーを参照してください。
各ウィンドウ指定には次のフィールドが含まれます:
フィールド | Type | 説明 |
|---|---|---|
| String | 必須。ウィンドウの順序を決定するフィールドです。(1) |
| String | 必須。ウィンドウの範囲。サポートされている |
| String | 必須。集計方法。サポートされている値： |
| String | オプション。Databricks Runtime 18.1およびYAML仕様バージョン1.1以降が必要です。「 |
(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 以降が必要であり、アンカー行がウィンドウに含まれるかどうかを制御します。The default isexclusive.アンカー行を含めるか除外するを参照してください。leading <value> <unit> [inclusive | exclusive]：アンカー行から、指定された時間単位で前方へ進む行。たとえばleading 3 month。オプションのinclusiveまたはexclusive修飾子には Databricks Runtime 18.1 および YAML 仕様バージョン 1.1 以降が必要であり、アンカー行がウィンドウに含まれるかどうかを制御します。The default isexclusive.アンカー行を含めるか除外するを参照してください。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
マテリアライゼーション
パブリックプレビュー
この機能は パブリック プレビュー段階です。
materializationフィールドは、マテリアライズドビューを使用した自動クエリー高速化を構成します。マテリアライゼーションの仕組み、要件、ベストプラクティスに関する詳細な情報については、「メトリクス ビューのマテリアライゼーション」を参照してください。
パラメーターを定義するメトリクスビューをマテリアライズすることはできません。
materializationフィールドには、次のトップレベルフィールドが含まれます。
フィールド | Type | 説明 |
|---|---|---|
| String | オプション。更新スケジュール。マテリアライズドビューのスケジュール句と同じ構文を使用します。省略した場合、マテリアライゼーションは手動でのみ更新されます。 |
| String | 必須。 |
| Array | 必須。マテリアライズするマテリアライズドビューのリスト。各エントリには、以下で説明するフィールドが必要です。 |
materialized_viewsのエントリには、次のフィールドが含まれます。
フィールド | Type | 説明 |
|---|---|---|
| String | 必須。マテリアライゼーションの名前です。 |
| String | 必須。マテリアライゼーションの種類。サポートされている値： |
| Array | 条件付き。マテリアライズするフィールド名の一覧です。 |
| Array | 条件です。マテリアライズする測定値名のリスト。 |
| オブジェクト | オプション。マテリアライゼーションのクラスタリング列。マテリアライズドビューの |
| Array | オプション。マテリアライゼーションをパーティション分割するための列のリスト。マテリアライズドビューの |
マテリアライゼーションブロックは、fields:ではなくdimensions:キーワードを使用します。トップレベルの定義がfields:を使用している場合でも、具現化するフィールドを一覧表示する際はdimensions:を使用します。
マテリアライゼーションの例
次の例では、複数のマテリアライゼーションを持つメトリクスビューを定義します。
version: 1.1
source: samples.tpch.orders
fields:
- name: order_date
expr: o_orderdate
- name: order_status
expr: o_orderstatus
measures:
- name: total_revenue
expr: SUM(o_totalprice)
- name: order_count
expr: COUNT(1)
materialization:
schedule: every 6 hours
mode: relaxed
materialized_views:
- name: baseline
type: unaggregated
- name: daily_status_metrics
type: aggregated
dimensions:
- order_date
- order_status
measures:
- total_revenue
- order_count
cluster_by:
cols:
- order_date
- order_status
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"
YAMLは、引用符で囲まれていないコロンをキーと値の区切り文字として解釈します。コロンを含む式は、二重引用符で囲む必要があります。
複数行の式
expr: |
CASE WHEN
revenue > 100 THEN 'High'
ELSE 'Low'
END
複数行の式には、expr:の後で|ブロック スカラーを使用します。正しく解析するには、すべての行をexprキーを超えて少なくとも2スペースインデントする必要があります。
YAML 1.1へのアップグレード
メトリクスビューをYAML仕様バージョン1.1にアップグレードするには、コメントの処理が以前のバージョンとは異なるため、注意が必要です。
コメントの種類
- **YAMLコメント（
#）**： インラインコメントまたは単一行コメントはYAMLファイルに直接記述されます。 - Unity Catalog コメント ：メトリクスビューまたはその列に対してUnity Catalogに保存されているコメントです。これらはYAMLコメントとは別です。
アップグレードに関する考慮事項
メトリクスビューでコメントを処理する方法に合うアップグレードパスを選択します。
オプション 1: ノートブックまたは SQL エディタを使用して YAML コメントを保持する
メトリクスビューに保持したいYAMLコメント（#）が含まれている場合は、次のステップを使用します：
- ノートブックまたはSQLエディタで
ALTER VIEWコマンドを使用します。 ASの後、$$..$$セクションに元のYAML定義をコピーします。versionの値を1.1に変更します。- メトリクスビューを保存します。
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)
$$
ALTER VIEWを実行すると、YAML定義のcommentフィールドに明示的に含まれていない限り、Unity Catalogのコメントは削除されます。Unity Catalogに表示されるコメントを保持するには、オプション 2を参照してください。
オプション 2：Unity Catalog コメントを保持する。
以下のガイダンスは、ノートブックまたはSQLエディタでALTER VIEWコマンドを使用する場合にのみ適用されます。YAMLエディタUIを使用してメトリクスビューをバージョン1.1にアップグレードする場合、YAMLエディタUIはUnity Catalogコメントを自動的に保持します。
- すべてのUnity Catalogコメントを、YAML定義の適切な
commentフィールドにコピーしてください。versionの値を1.1に変更します。 - メトリクスビューを保存します。
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仕様のバージョン履歴と各機能の最小ランタイム要件については、メトリクスビュー機能の可用性を参照してください。