YAML 구문 참조

메트릭 뷰 정의는 표준 YAML 표기법 구문을 따릅니다. 이 페이지에서는 메트릭 뷰를 정의하는 방법을 설명합니다.

YAML 사양에 대한 자세한 내용은 YAML 사양 1.2.2 설명서를 참조하세요.

YAML 개요

메트릭 뷰에 대한 YAML 정의에는 다음과 같은 최상위 필드가 포함됩니다.

• version: 기본값은 1.1입니다. 메트릭 뷰 사양의 버전입니다. 버전 사양 변경 로그를 참조하세요.
• source: 메트릭 뷰의 원본 데이터입니다. 테이블과 유사한 자산 또는 SQL 쿼리일 수 있습니다.
• joins: 선택 사항입니다. 별모양 스키마 및 눈송이 스키마 조인이 지원됩니다.
• filter: 선택 사항입니다. 모든 쿼리에 적용되는 SQL 부울 식입니다. 절에 WHERE 해당합니다.
• comment: 선택 사항입니다. 메트릭 뷰에 대한 설명입니다.
• dimensions: 차원 이름 및 식을 포함한 차원 정의의 배열입니다.
• measures: 집계 식 열의 배열입니다.

열 이름 참조

YAML 식에서 공백이나 특수 문자가 포함된 열 이름을 참조할 때, 열 이름의 공백이나 문자를 이스케이프하기 위해 백틱 기호로 묶어야 합니다. 식이 백틱으로 시작하고 YAML 값으로 직접 사용되는 경우 전체 식을 큰따옴표로 감싸야 합니다. 유효한 YAML 값은 백틱으로 시작해서는 안 됩니다.

서식 지정 예제

다음 예제를 사용하여 일반적인 시나리오에서 YAML의 서식을 올바르게 지정하는 방법을 알아봅니다.

열 이름 참조

다음 표에서는 포함된 문자에 따라 열 이름의 서식을 지정하는 방법을 보여줍니다.

식에 콜론 사용

여러 줄 들여쓰기

차원 정의

다음 예제에서는 차원을 정의하는 방법을 보여 줍니다.

dimensions:

  # Column name
  - name: Order date
    expr: o_orderdate

  # SQL expression
  - name: Order month
    expr: DATE_TRUNC('MONTH', `Order date`)

  # Referring to a column with a space in the name
  - name: Month of order
    expr: `Order month`

  # Multi-line expression
  - name: Order status
    expr: CASE
            WHEN o_orderstatus = 'O' THEN 'Open'
            WHEN o_orderstatus = 'P' THEN 'Processing'
            WHEN o_orderstatus = 'F' THEN 'Fulfilled'
          END

측정값 정의

다음 예제에서는 측정값을 정의하는 방법을 보여 줍니다.

measures:

  # Basic aggregation
  - name: Total revenue
    expr: SUM(o_totalprice)

  # Basic aggregation with ratio
  - name: Total revenue per customer
    expr: SUM(`Total revenue`) / COUNT(DISTINCT o_custkey)

  # Measure-level filter
  - name: Total revenue for open orders
    expr: COUNT(o_totalprice) FILTER (WHERE o_orderstatus='O')

  # Measure-level filter with multiple aggregate functions
  # filter needs to be specified for each aggregate function in the expression
  - name: Total revenue per customer for open orders
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus='O')/COUNT(DISTINCT o_custkey) FILTER (WHERE o_orderstatus='O')

YAML을 CREATE VIEW 사용하여 열 이름 매핑

메트릭 뷰를 CREATE VIEW으로 생성하고 column_list를 사용할 때, 시스템은 YAML로 정의된 열 (측정값 및 차원)을 이름이 아닌 위치별로 column_list에 매핑합니다.

다음 예제와 같이 표준 SQL 동작을 따릅니다.

CREATE VIEW v (col1, col2) AS SELECT a, b FROM table;

이 예에서 a는 col1로 매핑되고, b는 col2로 매핑됩니다. 원래 이름과는 무관합니다.

YAML을 1.1로 업그레이드

메트릭 뷰를 YAML 사양 버전 1.1로 업그레이드하려면 이전 버전과 다르게 주석이 처리되므로 주의해야 합니다.

주석 유형

• YAML 주석(#): # 기호를 사용하여 YAML 파일에 직접 작성된 인라인 또는 한 줄 주석입니다.
• Unity 카탈로그 주석: 메트릭 뷰 또는 해당 열(차원 및 측정값)에 대해 Unity 카탈로그에 저장된 주석입니다. YAML 주석과는 별개입니다.

업그레이드 고려 사항

메트릭 보기에서 주석을 처리하는 방법과 일치하는 업그레이드 경로를 선택합니다. 다음 옵션은 사용 가능한 방법을 설명하고 예제를 제공합니다.

옵션 1: Notebook 또는 SQL 편집기를 사용하여 YAML 주석 유지

메트릭 보기에 유지하려는 YAML 주석(#)이 포함된 경우 다음 단계를 사용합니다.

1. Notebook 또는 SQL 편집기에서 ALTER VIEW 명령을 사용하십시오.

2. 원래 YAML 정의를 AS 이후의 $$..$$ 섹션으로 복사합니다. 버전 값을 1.1로 변경합니다.

3. 메트릭 뷰를 저장합니다.

ALTER VIEW metric_view_name AS
$$
# Inline comments are preserved in the notebook
version: 1.1
source: samples.tpch.orders
dimensions:
- name: order_date # Inline comments are preserved in the notebook
  expr: o_orderdate
measures:
# Commented out definition is preserved
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

옵션 2: Unity 카탈로그 주석 유지

1. 모든 Unity 카탈로그 주석을 YAML 정의의 적절한 comment 필드에 복사합니다. 버전 값을 1.1로 변경합니다.

2. 메트릭 뷰를 저장합니다.

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


dimensions:
- 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"
$$

버전 사양 변경 로그

버전 1.1(Databricks Runtime 17.2 이상 필요)

• 추가된 내용:
  • 의미 체계 메타데이터 기능을 지원합니다. 메트릭 뷰에서 의미 체계 메타데이터 사용을 참조하세요.
  • 메트릭 뷰, 차원 또는 측정값을 설명하는 선택적 YAML comment 필드를 지원합니다.

버전 0.1(Databricks Runtime 16.4~17.1 필요)

• 메트릭 뷰 YAML 사양의 초기 릴리스입니다.