olai-uc-common 0.0.3

Shared types, generated Unity Catalog models, and storage/REST abstractions for the Unity Catalog server and client crates.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

//! Deserializable model of the Unity Catalog metric-view YAML (the `1.1`
//! user-facing surface).
//!
//! A metric view is a semantic layer over a base relation: it names
//! [`Dimension`]s (group-by expressions) and [`Measure`]s (aggregate
//! expressions) as SQL strings. Unity Catalog returns this YAML as a table's
//! definition when the table is a metric view.
//!
//! Reference: <https://docs.databricks.com/aws/en/business-semantics/metric-views/yaml-reference>
//!
//! This models the field surface needed to lower a metric view into a query plan
//! and to derive its dependencies ([`super::deps`]); fields not yet exercised by
//! the lowering ([`Join`], `window`, `materialization`) are captured loosely.

use serde::Deserialize;

/// A Unity Catalog metric view, deserialized from its YAML definition.
#[derive(Debug, Clone, Deserialize)]
pub struct MetricView {
    /// Spec version, e.g. `"1.1"`. Carried through for diagnostics; the lowering
    /// does not branch on it.
    #[serde(default)]
    pub version: Option<String>,

    /// The base relation: a three-part `catalog.schema.table` name, or an inline
    /// SQL query.
    pub source: String,

    /// Optional SQL boolean predicate applied to every query against the view.
    #[serde(default)]
    pub filter: Option<String>,

    /// Star/snowflake joins.
    #[serde(default)]
    pub joins: Vec<Join>,

    /// Group-by expressions. The UC docs use `fields` as the canonical synonym
    /// for `dimensions`; accept either.
    #[serde(default, alias = "fields")]
    pub dimensions: Vec<Dimension>,

    /// Aggregate expressions.
    #[serde(default)]
    pub measures: Vec<Measure>,
}

/// A group-by expression exposed by the metric view.
#[derive(Debug, Clone, Deserialize)]
pub struct Dimension {
    /// Output column name for the dimension.
    pub name: String,
    /// SQL expression evaluated against the source relation.
    pub expr: String,
}

/// An aggregate expression exposed by the metric view.
#[derive(Debug, Clone, Deserialize)]
pub struct Measure {
    /// Output column name for the measure.
    pub name: String,
    /// SQL aggregate expression, e.g. `SUM(o_totalprice)`.
    pub expr: String,
}

/// A join in a star/snowflake metric view.
#[derive(Debug, Clone, Deserialize)]
pub struct Join {
    /// Alias for the joined relation.
    pub name: String,
    /// Joined relation: three-part name or inline SQL.
    pub source: String,
    /// SQL join condition (`on`). Mutually exclusive with `using` in practice.
    #[serde(default)]
    pub on: Option<String>,
    /// Columns to join on by name, as an alternative to `on`.
    #[serde(default)]
    pub using: Vec<String>,
    /// `many_to_one` (default) or `one_to_many`.
    #[serde(default)]
    pub cardinality: Option<String>,
}

impl MetricView {
    /// Parse a metric view from its YAML definition.
    pub fn from_yaml(yaml: &str) -> Result<Self, serde_yml::Error> {
        serde_yml::from_str(yaml)
    }
}