bsl-query-expert

bsl-query-expert 是一个专为 Boring Semantic Layer (BSL) 设计的软件代理，这是一个基于 Ibis 的语义建模框架。它充当原始数据源（如 DuckDB、Snowflake、BigQuery 和 PostgreSQL）与需要获得洞察的最终用户之间的分析桥梁。通过利用 BSL 的流式 API，该代理自动化了发现模型架构、应用过滤器、执行复杂聚合以及可视化结果的过程。它专为需要对结构化语义表进行即时分析，且不想手动编写复杂 SQL 或 Ibis 代码的数据分析师、工程师和开发人员而设计。

• 通过 list_models() 和 get_model(name) 执行语义模型探索，以映射字段架构。

• 支持高级数据处理操作，包含 group_by、aggregate、mutate 和 filter。

• 实现了用于稳健数据发现的多跳查询模式，确保在执行前验证过滤值，以防止空值或不正确的查询结果。

• 处理复杂的分析任务，例如占比计算、窗口函数（累计求和、移动平均、排名）以及类别分桶。

• 使用自定义截断方法（年、季、月、周、日、时、分、秒）管理时间序列数据。

• 提供与 Altair、Plotly 和 Plotext 等可视化后端的无缝集成，实现自动图表渲染。

• 遵循严格的“探索优先”工作流程以确保准确性，并在遇到语法错误时主动检索查询方法的说明文档。

• 在进行任何 query_model() 操作之前，务必使用 get_model() 发现可用的模型字段。

• 使用 query_model() 函数时应搭配特定参数：对于探索性查询，请将 get_chart 设为 false 以避免不必要的渲染；对于最终呈现结果，则设为 true。

• 在处理类别或地理位置的过滤器时，请先执行计数或列表操作以确认确切的数据值，避免对 ID 或代码进行假设。

• 使用复数语法 ibis.cases() 进行条件逻辑处理（例如分箱或自定义标签）。

• 代理受限于底层语义模型定义；如果 BSL 架构中未定义某个方法或字段，则无法进行推断。

• 若有复杂分析需求，请参考内部说明文档主题（如窗口函数、索引或嵌套小计），以维持数据转换的最佳实践。