将 Metric View 序列化为 YAML

2025-01-27
Greg Baldini

Applies to:

❌ ~~Tabular Editor 2~~
Tabular Editor 3 (Available since 3.25.0)
❌ ~~Desktop~~

❌ ~~Business~~

✔ Enterprise

本操作指南演示如何将 Metric View 序列化回 YAML 格式：既可以作为字符串获取，也可以保存到文件中。

Warning

MVP 仅支持 v0.1 的 Metric View 属性。如果加载的 Metric View 中包含任何 v1.1 元数据，系统会静默忽略；在序列化时，这些元数据将会丢失。不要覆盖包含 v1.1 元数据的源 YAML 文件。

对这些代码示例的 Metric View 进行反序列化

本操作指南使用一个示例电商 Metric View 来表示销售数据，其中三个维度表（product、customer、date）连接到一个事实表（orders）。如果你想在阅读本操作指南其余部分时跟着代码一起操作，请先运行下面的代码片段

SemanticBridge.MetricView.Deserialize("""
    version: 0.1
    source: sales.fact.orders
    joins:
      - name: product
        source: sales.dim.product
        on: source.product_id = product.product_id
      - name: customer
        source: sales.dim.customer
        on: source.customer_id = customer.customer_id
      - name: date
        source: sales.dim.date
        on: source.order_date = date.date_key
    dimensions:
      - name: product_name
        expr: product.product_name
      - name: product_category
        expr: product.category
      - name: customer_segment
        expr: customer.segment
      - name: order_date
        expr: date.full_date
      - name: order_year
        expr: date.year
      - name: order_month
        expr: date.month_name
    measures:
      - name: total_revenue
        expr: SUM(revenue)
      - name: order_count
        expr: COUNT(order_id)
      - name: avg_order_value
        expr: AVG(revenue)
      - name: unique_customers
        expr: COUNT(DISTINCT customer_id)
    """);

序列化为字符串

使用 Serialize() 获取 YAML 表示形式：

var yaml = SemanticBridge.MetricView.Serialize();

var sb = new System.Text.StringBuilder();
sb.AppendLine("YAML output:");
sb.AppendLine("------------");
sb.AppendLine(yaml);
Output(sb.ToString());

保存到文件

使用 Save(path) 将 YAML 直接写入磁盘：

var path = "C:/MetricViews/updated-sales-metrics.yaml";

SemanticBridge.MetricView.Save(path);

Output($"Metric View saved to: {path}");

往返式工作流

一种常见的工作流是加载、修改并保存 Metric View：

using System.Globalization;
using MetricView = TabularEditor.SemanticBridge.Platforms.Databricks.MetricView;

// The Metric View is already loaded from the include above

var view = SemanticBridge.MetricView.Model;
var textInfo = CultureInfo.CurrentCulture.TextInfo;

// Modify: rename dimensions from snake_case to Title Case
var renamed = view.Dimensions.Select(dim => new MetricView.Dimension
{
    Name = textInfo.ToTitleCase(dim.Name.Replace('_', ' ')),
    Expr = dim.Expr
}).ToList();

view.Dimensions.Clear();
foreach (var dim in renamed)
{
    view.Dimensions.Add(dim);
}

// Serialize to see the result
var yaml = SemanticBridge.MetricView.Serialize();

var sb = new System.Text.StringBuilder();
sb.AppendLine("Modified YAML:");
sb.AppendLine("--------------");
sb.AppendLine(yaml);
Output(sb.ToString());

输出：

修改后的 YAML：
--------------
version: 0.1
source: sales.fact.orders
joins:
- name: product
  source: sales.dim.product
  on: source.product_id = product.product_id
- name: customer
  source: sales.dim.customer
  on: source.customer_id = customer.customer_id
- name: date
  source: sales.dim.date
  on: source.order_date = date.date_key
dimensions:
- name: Product Name
  expr: product.product_name
- name: Product Category
  expr: product.category
- name: 客户分段
  expr: customer.segment
- name: Order Date
  expr: date.full_date
- name: Order Year
  expr: date.year
- name: Order Month
  expr: date.month_name
measures:
- name: total_revenue
  expr: SUM(revenue)
- name: order_count
  expr: COUNT(order_id)
- name: avg_order_value
  expr: AVG(revenue)
- name: unique_customers
  expr: COUNT(DISTINCT customer_id)