YAML söz dizimi başvurusu

Ölçüm görünümü tanımları standart YAML gösterimi söz dizimini izler. Bu sayfada ölçüm görünümünün nasıl tanımlanacağı açıklanmaktadır.

YAML belirtimleri hakkında daha fazla bilgi edinmek için YAML Belirtimi 1.2.2 belgelerine bakın.

YAML'ye genel bakış

Ölçüm görünümünün YAML tanımı aşağıdaki üst düzey alanları içerir:

• version: varsayılan olarak 1.1. Bu, metrik görünüm belirtiminin versiyonudur. Bkz . Sürüm belirtimi değişiklik günlüğü.
• source: Ölçüm görünümü için kaynak veriler. Bu tablo benzeri bir varlık veya SQL sorgusu olabilir.
• joins: İsteğe bağlı. Yıldız şeması ve snowflake şeması birleşimleri desteklenir.
• filter: İsteğe bağlı. Tüm sorgular için geçerli olan bir SQL boole ifadesi; yan tümcesine WHERE eşdeğerdir.
• comment: İsteğe bağlı. Ölçüm görünümünün açıklaması.
• dimensions: Boyut adı ve ifadesi de dahil olmak üzere boyut tanımları dizisi.
• measures: Toplama ifadesi sütunları dizisi.

Sütun adı referansları

YAML ifadelerinde boşluk veya özel karakterler içeren sütun adlarına başvururken, boşluktan veya karakterden kaçmak için sütun adını arka köşelere koyun. İfade bir backtick ile başlıyorsa ve doğrudan YAML değeri olarak kullanılıyorsa, ifadenin tamamını çift tırnak içine alın. Geçerli YAML değerleri bir backtick ile başlayamaz.

Biçimlendirme örnekleri

Yaygın senaryolarda YAML'yi doğru biçimlendirmeyi öğrenmek için aşağıdaki örnekleri kullanın.

Bir sütun adına başvurun

Aşağıdaki tabloda, sütun adlarının içerdikleri karakterlere bağlı olarak nasıl biçimlendirilir gösterilmektedir.

Büyük/küçük harf durumu	Kaynak sütun adları	Referans ifadeleri	Notes
Boşluk yok	revenue	expr: "revenue" expr: 'revenue' expr: revenue	Sütun adının çevresinde çift tırnak, tek tırnak veya tırnak işareti kullanma.
Boşluklu	First Name	expr: "`First Name`"	Kaçış boşluklarını kullanmak için arka uçları kullanın. İfadenin tamamını çift tırnak içine alın.
SQL ifadesinde boşluklar içeren sütun adı	First Name ve Last Name	expr: CONCAT(`First Name`, , `Last Name`)	İfade arka uçlarla başlamıyorsa çift tırnak işareti gerekmez.
Kaynak sütun adına tırnak işaretleri eklenir	"name"	expr: '`"name"`'	Sütun adındaki çift tırnak işaretinden kurtulmak için arka uçları kullanın. YAML tanımında o ifadeyi tek tırnak işaretleri içine alın.

İfadeleri iki nokta üst üste ile kullanma

Büyük/küçük harf durumu	Expression	Notes
İki noktalı ifadeler	expr: "CASE WHEN Müşteri Katmanı = 'Enterprise: Premium' THEN 1 ELSE 0 END"	Doğru yorumlama için ifadenin tamamını çift tırnak içine alma

Uyarı

YAML, sıralanmamış iki nokta üst üsteleri anahtar-değer ayırıcıları olarak yorumlar. Her zaman, iki nokta içeren ifadelerin çevresinde çift tırnak kullanarak belirtin.

Çok satırlı girinti

Büyük/küçük harf durumu	Expression	Notes
Çok satırlı girinti	expr: \| CASE WHEN revenue > 100 THEN 'High' ELSE 'Low' END	İlk satırın altındaki ifadeyi girintile

Uyarı

| Çok satırlı ifadeler için sonraki expr: blok skaler değerini kullanın. Doğru ayrıştırma için tüm satırlar anahtarın expr ötesinde en az iki boşluk girintili olmalıdır.

Bir boyut tanımla

Aşağıdaki örnekte boyutların nasıl tanımlanacağı gösterilmektedir:

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

Ölçü tanımlama

Aşağıdaki örnekte ölçülerin nasıl tanımlanacağı gösterilmektedir:

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 ile CREATE VIEW içinde sütun adı eşleştirme

CREATE VIEW ve column_list kullanarak bir ölçü görünümü oluşturduğunuzda, sistem YAML ile tanımlanan sütunları (ölçüler ve boyutlar) column_list üzerinde ada göre değil, konuma göre eşler.

Bu, aşağıdaki örnekte gösterildiği gibi standart SQL davranışını izler:

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

Bu örnekte, acol1'e ve bcol2'e özgün adlarından bağımsız olarak eşlenir.

YAML'nizi 1.1 sürümüne yükseltme

Ölçüm görünümünü YAML belirtimi sürüm 1.1'e yükseltmek dikkat gerektirir çünkü açıklamalar önceki sürümlerden farklı işlenir.

Açıklama türleri

• YAML açıklamaları (#): # simgesi kullanılarak doğrudan YAML dosyasında yazılan satır içi veya tek satırlı açıklamalar.
• Unity Kataloğu açıklamaları: Ölçüm görünümü veya sütunları (boyutlar ve ölçüler) için Unity Kataloğu'nda depolanan açıklamalar. Bunlar YAML açıklamalarından ayrıdır.

Yükseltmeyle ilgili dikkat edilmesi gerekenler

Ölçüm görünümünüzde açıklamaları işlemek istediğiniz şekilde eşleşen yükseltme yolunu seçin. Aşağıdaki seçenekler kullanılabilir yaklaşımları açıklar ve örnekler sağlar.

1. Seçenek: Not defterlerini veya SQL düzenleyicisini kullanarak YAML açıklamalarını koruma

Ölçüm görünümünüzde tutmak istediğiniz YAML açıklamaları (#) varsa aşağıdaki adımları kullanın:

1. ALTER VIEW Komutunu not defterinde veya SQL düzenleyicisinde kullanın.

2. Özgün YAML tanımını AS'den sonra $$..$$ bölümüne kopyalayın. Sürüm değerini 1.1 olarak değiştirin.

3. Ölçüm görünümünü kaydedin.

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

Uyarı

Çalıştırıldığında ALTER VIEW , YAML tanımının alanlarına açıkça dahil comment edilmedikleri sürece Unity Kataloğu açıklamaları kaldırılır. Unity Kataloğu'nda gösterilen açıklamaları korumak istiyorsanız 2. seçeneğe bakın.

Seçenek 2: Unity Kataloğu açıklamalarını koru

Uyarı

Aşağıdaki kılavuz yalnızca komutu bir not defterinde veya SQL düzenleyicisinde kullanırken ALTER VIEW geçerlidir. ÖLÇÜM görünümünüzü YAML düzenleyicisi kullanıcı arabirimini kullanarak sürüm 1.1'e yükseltirseniz Unity Kataloğu açıklamalarınız otomatik olarak korunur.

1. Tüm Unity Kataloğu açıklamalarını YAML tanımınızdaki uygun comment alanlara kopyalayın. Sürüm değerini 1.1 olarak değiştirin.

2. Ölçüm görünümünü kaydedin.

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

Sürüm tanımı değişiklik kaydı

Sürüm 1.1 (Databricks Runtime 17.2 veya üzeri gerektirir)

• Eklendi:
  • Anlamsal meta veri özellikleri desteği. Bkz . Ölçüm görünümlerinde anlam meta verilerini kullanma.
  • Ölçüm görünümünü, boyutlarını veya ölçülerini açıklamak için isteğe bağlı YAML comment alanı desteği.

Sürüm 0.1 (Databricks Runtime 16.4'ten 17.1'e kadar gerektirir)

• Ölçüm görünümü YAML belirtiminin ilk sürümü.