rust_store_core/dialect/
ir.rs

1//! SQL 中间表示（IR）
2
3use serde_json::{json, Value};
4
5/// 一条参数化 SQL 语句（参数位置用 `?` / `$n` 占位，params 顺序对应）
6#[derive(Debug, Clone, PartialEq)]
7pub struct SqlStmt {
8    /// SQL 文本（标识符已按后端加引号，值全部参数化）
9    pub text: String,
10    /// 绑定参数（按占位顺序）
11    pub params: Vec<Value>,
12    /// 是否为写语句
13    pub is_write: bool,
14    /// SELECT 时的「列 → JSON 还原路径」元数据（见 `row_shape`）
15    pub row_shape: Option<RowShape>,
16    /// RETURNING 列（PG/SQLite 写语句回读用；MySQL 无）
17    pub returning: Vec<String>,
18}
19
20impl SqlStmt {
21    pub fn select(text: String, params: Vec<Value>, row_shape: RowShape) -> Self {
22        SqlStmt {
23            text,
24            params,
25            is_write: false,
26            row_shape: Some(row_shape),
27            returning: Vec::new(),
28        }
29    }
30
31    pub fn write(text: String, params: Vec<Value>) -> Self {
32        SqlStmt {
33            text,
34            params,
35            is_write: true,
36            row_shape: None,
37            returning: Vec::new(),
38        }
39    }
40
41    pub fn to_value(&self) -> Value {
42        json!({
43            "text": self.text,
44            "params": self.params,
45            "isWrite": self.is_write,
46            "rowShape": self.row_shape.as_ref().map(|r| r.to_value()).unwrap_or(Value::Null),
47            "returning": self.returning,
48        })
49    }
50}
51
52/// SELECT 输出的一列：SQL 别名（如 `t1_title` / `rel0_amount`）→ JSON 里的嵌套还原路径
53#[derive(Debug, Clone, PartialEq)]
54pub struct RowShape {
55    /// 列 → { jsonPath, isArray }。jsonPath 形如 `["title"]` 或 `["items","amount"]`，
56    /// 表示该列应嵌套还原到文档的哪个位置；isArray 表示该字段是关系数组（聚合还原）。
57    pub columns: Vec<RowCol>,
58    /// `__present` 哨兵列的别名（缺失 vs null 三态，F-07/H-01）：该列存每行
59    /// 「哪些标量字段显式存在」的集合。读取时标量列值为 null，仅当字段存在于
60    /// 该集合才还原为 `key: null`，否则（缺失）不产出该键。`None` 表示本条语句
61    /// 未查该列（如 count / 关系聚合），还原时不做存在性判定。
62    pub present_alias: Option<String>,
63}
64
65#[derive(Debug, Clone, PartialEq)]
66pub struct RowCol {
67    pub alias: String,
68    pub json_path: Vec<String>,
69    /// 是否为关系聚合数组字段（`many` 关系的子文档）
70    pub is_array: bool,
71    /// 是否为 `one` 关系（LEFT JOIN 后还原为对象或 `null`，而非数组）
72    pub one: bool,
73    /// 沿 `json_path` 每一级关系的基数（`true` = `one`）。长度 = 关系级数
74    /// （`json_path.len() - 1`）；根标量列为空。嵌套关系靠它逐级决定「对象 / 数组」。
75    pub ones: Vec<bool>,
76    /// 若为空：标量直接取该列；若非空：构造子文档
77    pub sub_shape: Option<RowShape>,
78    /// 值恒「存在」：为 `null` 时也强制写入（不依赖 `__present` 哨兵）。用于归一聚合
79    /// 计算列（§9.2(2)）—— 空集 `$sum/$avg/$min/$max` 的语义是显式 `null`（§9.7），
80    /// 与 Mongo 输出逐行对齐。
81    pub always: bool,
82    /// §9.7「布尔归一」：该输出列对应 schema 的 `boolean` 字段 → 行还原时把 SQL 的
83    /// `0/1` 归一为 JSON `bool`（对齐 Mongo；PG 原生 `BOOLEAN` 已是 bool，归一为 no-op）。
84    /// 依据**schema 声明类型**而非驱动元数据，故对任意用户 DDL 都成立。
85    pub is_bool: bool,
86}
87
88impl RowShape {
89    pub fn empty() -> Self {
90        RowShape {
91            columns: Vec::new(),
92            present_alias: None,
93        }
94    }
95
96    pub fn to_value(&self) -> Value {
97        let cols: Vec<Value> = self
98            .columns
99            .iter()
100            .map(|c| {
101                json!({
102                    "alias": c.alias,
103                    "path": c.json_path,
104                    "isArray": c.is_array,
105                    "one": c.one,
106                    "ones": c.ones,
107                    "subShape": c.sub_shape.as_ref().map(|s| s.to_value()).unwrap_or(Value::Null),
108                    "always": c.always,
109                    "bool": c.is_bool,
110                })
111            })
112            .collect();
113        json!({
114            "columns": cols,
115            "present": self.present_alias.clone().unwrap_or_default(),
116        })
117    }
118}
119
120impl RowCol {
121    pub fn scalar(alias: &str, path: &[&str]) -> Self {
122        RowCol {
123            alias: alias.to_string(),
124            json_path: path.iter().map(|s| s.to_string()).collect(),
125            is_array: false,
126            one: false,
127            ones: Vec::new(),
128            sub_shape: None,
129            always: false,
130            is_bool: false,
131        }
132    }
133
134    /// 标量列 + 布尔标记（§9.7）：来自 schema `boolean` 字段的输出列
135    pub fn scalar_bool(alias: &str, path: &[&str], is_bool: bool) -> Self {
136        let mut c = RowCol::scalar(alias, path);
137        c.is_bool = is_bool;
138        c
139    }
140
141    /// 归一聚合计算列（§9.2(2)）：根标量，且 `null` 也强制写入（见 [`RowCol::always`]）
142    pub fn computed(alias: &str, path: &[&str]) -> Self {
143        RowCol {
144            alias: alias.to_string(),
145            json_path: path.iter().map(|s| s.to_string()).collect(),
146            is_array: false,
147            one: false,
148            ones: Vec::new(),
149            sub_shape: None,
150            always: true,
151            is_bool: false,
152        }
153    }
154
155    pub fn array(alias: &str, sub_shape: RowShape) -> Self {
156        RowCol {
157            alias: alias.to_string(),
158            json_path: vec![alias.to_string()],
159            is_array: true,
160            one: false,
161            ones: vec![false],
162            sub_shape: Some(sub_shape),
163            always: false,
164            is_bool: false,
165        }
166    }
167}
rust_store_core/dialect/ir.rs

rust_store_core/dialect/
ir.rs
