Referensi sintaks YAML

Definisi tampilan metrik mengikuti sintaks notasi YAML standar. Halaman ini menjelaskan cara menentukan tampilan metrik.

Lihat dokumentasi SPESIFIKASI YAML 1.2.2 untuk mempelajari selengkapnya tentang spesifikasi YAML.

Gambaran umum YAML

Definisi YAML untuk tampilan metrik menyertakan bidang tingkat atas berikut:

• version: Diatur ke 1.1. Ini adalah versi spesifikasi tampilan metrik. Lihat Riwayat perubahan spesifikasi versi.
• source: Data sumber untuk tampilan metrik. Ini bisa menjadi aset seperti tabel atau kueri SQL.
• joins: Opsional. Skema bintang dan gabungan skema snowflake didukung.
• filter: Opsional. Ekspresi boolean SQL yang berlaku untuk semua kueri; setara dengan WHERE klausa.
• comment: Opsional. Deskripsi tampilan metrik.
• dimensions: Sebuah array yang berisi definisi-definisi dimensi, termasuk nama dimensi dan ekspresi.
• measures: Array kolom ekspresi agregat.

Referensi nama kolom

Saat mereferensikan nama kolom yang berisi spasi atau karakter khusus dalam ekspresi YAML, tempatkan nama kolom dalam tanda backtick untuk mengabaikan spasi atau karakter tersebut. Jika ekspresi dimulai dengan backtick dan digunakan langsung sebagai nilai YAML, bungkus seluruh ekspresi dalam tanda kutip ganda. Nilai yang valid dalam YAML tidak boleh dimulai dengan tanda backtick.

Contoh pemformatan

Gunakan contoh berikut untuk mempelajari cara memformat YAML dengan benar dalam skenario umum.

Mereferensikan nama kolom

Tabel berikut ini memperlihatkan cara memformat nama kolom bergantung pada karakter yang dikandungnya.

Perkara	Nama kolom sumber	Ekspresi referensi	Catatan
Tidak ada spasi	revenue	expr: "revenue" expr: 'revenue' expr: revenue	Gunakan tanda kutip ganda, tanda kutip tunggal, atau tanpa tanda kutip di sekitar nama kolom.
Dengan spasi	First Name	expr: "`First Name`"	Gunakan backtick untuk menghindari spasi. Sertakan seluruh ekspresi dalam tanda kutip ganda.
Nama kolom dengan spasi dalam ekspresi SQL	First Name dan Last Name	expr: CONCAT(`First Name`, , `Last Name`)	Jika ekspresi tidak dimulai dengan backtick, tanda kutip ganda tidak diperlukan.
Tanda kutip disertakan dalam nama kolom sumber	"name"	expr: '`"name"`'	Gunakan backtick untuk menghindari tanda kutip ganda dalam nama kolom. Sertakan ekspresi tersebut dalam tanda kutip tunggal dalam definisi YAML.

Gunakan ekspresi dengan titik dua

Perkara	Expression	Catatan
Ekspresi dengan titik dua	expr: "CASE WHEN Tingkat Pelanggan = 'Enterprise: Premium' THEN 1 ELSE 0 END"	Membungkus seluruh ekspresi dalam tanda kutip ganda untuk interpretasi yang benar

Nota

YAML menafsirkan titik dua yang tidak dikutip sebagai pemisah nilai kunci. Selalu gunakan tanda kutip ganda di sekitar ekspresi yang menyertakan titik dua.

Indentasi multibaris

Perkara	Expression	Catatan
Indentasi multibaris	expr: \| CASE WHEN revenue > 100 THEN 'High' ELSE 'Low' END	Inden pernyataan di bawah baris pertama

Nota

| Gunakan skalar blok setelah expr: untuk ekspresi multibaris. Semua baris harus diindentasi setidaknya dua spasi di luar elemen expr agar dapat diurai dengan benar.

Menentukan dimensi

Contoh berikut menunjukkan cara menentukan dimensi:

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

Menentukan ukuran

Contoh berikut menunjukkan cara menentukan langkah-langkah:

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')

Pemetaan nama kolom dengan CREATE VIEW YAML

Saat Anda membuat tampilan metrik menggunakan CREATE VIEW dengan column_list, sistem memetakan kolom yang ditentukan YAML (pengukuran dan dimensi) ke column_list berdasarkan posisi, bukan berdasarkan nama.

Ini mengikuti perilaku SQL standar seperti yang ditunjukkan dalam contoh berikut:

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

Dalam contoh ini, a memetakan ke col1, dan b memetakan ke col2, terlepas dari nama aslinya.

Tingkatkan YAML Anda ke 1.1

Meningkatkan tampilan metrik ke spesifikasi YAML versi 1.1 memerlukan perhatian, karena komentar ditangani secara berbeda dari pada versi sebelumnya.

Jenis komentar

• Komentar YAML (#): Komentar sebaris atau baris tunggal yang ditulis langsung dalam file YAML menggunakan simbol # .
• Komentar Katalog Unity: Komentar yang disimpan di Katalog Unity untuk tampilan metrik atau kolomnya (dimensi dan ukuran). Ini terpisah dari komentar YAML.

Pertimbangan peningkatan

Pilih jalur peningkatan yang cocok dengan cara yang Anda inginkan untuk menangani komentar dalam tampilan metrik Anda. Opsi berikut menjelaskan pendekatan yang tersedia dan memberikan contoh.

Opsi 1: Mempertahankan komentar YAML menggunakan notebook atau editor SQL

Jika tampilan metrik Anda berisi komentar YAML (#) yang ingin Anda simpan, gunakan langkah-langkah berikut:

1. ALTER VIEW Gunakan perintah di notebook atau editor SQL.

2. Salin definisi YAML asli ke $$..$$ bagian setelah AS. Ubah nilai versi menjadi 1.1.

3. Simpan tampilan metrik.

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)
$$

Peringatan

Menjalankan ALTER VIEW akan menghapus komentar Unity Catalog kecuali jika secara eksplisit disertakan pada bidang comment dalam definisi YAML. Jika Anda ingin mempertahankan komentar yang ditampilkan di Katalog Unity, lihat opsi 2.

Opsi 2: Mempertahankan komentar Katalog Unity

Nota

Panduan berikut ini hanya berlaku saat menggunakan ALTER VIEW perintah di notebook atau editor SQL. Jika Anda meningkatkan tampilan metrik ke versi 1.1 menggunakan UI editor YAML, komentar Katalog Unity Anda akan dipertahankan secara otomatis.

1. Salin semua komentar Katalog Unity ke bidang yang sesuai comment dalam definisi YAML Anda. Ubah nilai versi menjadi 1.1.

2. Simpan tampilan metrik.

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

Log perubahan spesifikasi versi

Versi 1.1 (memerlukan Databricks Runtime 17.2 atau lebih tinggi)

• Ditambahkan:
  • Dukungan untuk fitur metadata semantik. Lihat Menggunakan metadata semantik dalam tampilan metrik.
  • Dukungan untuk bidang YAML comment opsional untuk menjelaskan tampilan metrik, dimensi, atau pengukuran.

Versi 0.1 (memerlukan Databricks Runtime 16.4 hingga 17.1)

• Rilis awal spesifikasi tampilan metrik YAML.