bsl-model-builder

BSL Model Builder 是一个专业的软件代理技能，旨在协助数据工程师与分析师使用 Boring Semantic Layer (BSL) 在原始数据上构建语义模型。它利用 Ibis 框架提供与数据库无关的接口，支持包括 DuckDB、Snowflake、BigQuery 和 PostgreSQL 等多种引擎。通过将原始 SQL 逻辑抽象化为可重用的语义组件，该构建器实现了一致的指标报告、结构化的关联逻辑以及适用于生产环境的模块化数据定义。

• 定义复杂的语义表，将 Ibis 表达式映射为具名的维度与度量。

• 通过时间截断（如年、季、月、周、日）实现分层分组，以进行时间序列分析。

• 使用 t.all() 构建复杂的聚合逻辑，包括简单的总和、平均值以及市场份额等比例度量。

• 通过一对多、一对一与交叉关联处理关联数据，支持自定义连接键与标准 SQL 连接类型（左、内、外连接）。

• 支持通过 Python 进行程序化定义与通过 YAML 文件进行声明式配置，有助于版本控制与可重现的工作流。

• 利用内置的 AI 友好文档功能，为维度和度量添加描述属性，提升下游基于 LLM 的数据代理对模型的理解与发现能力。

• 输入形式为原始 Ibis 关系或已建立的数据库连接配置，输出结构化的 SemanticTable 对象或合法的模型配置 YAML 文件。

• 使用 fluent API 链式调用 .with_dimensions()、.with_measures() 和 .join_many()，以保持代码简洁易读。

• 确保所有定义遵循 BSL 的核心原则：尽量避免使用原始 SQL，优先使用 Ibis 原生抽象以维持跨后端的移植性。

• 为了性能考量，建议将大型项目组织成独立的 YAML 文件，以改善团队环境中的维护性与协作效率。

• 注意限制：必须保持与底层 Ibis 表达式的兼容性，确保所有 lambda 函数或延迟表达式（使用 _. 语法）在目标 Ibis 表的范围内是有效的。