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 架構中未定義某個方法或欄位，則無法進行推論。

• 若有複雜分析需求，請參考內部說明文件主題（如視窗函數、索引或巢狀小計），以維持數據轉換的最佳實踐。