bsl-query-expert

The bsl-query-expert is a specialized software agent designed to interface with the Boring Semantic Layer (BSL), an Ibis-powered semantic modeling framework. It acts as an analytical bridge between raw data sources—such as DuckDB, Snowflake, BigQuery, and PostgreSQL—and end-users seeking actionable insights. By leveraging the BSL fluent API, the agent automates the process of discovering model schemas, applying filters, executing complex aggregations, and visualizing results. It is built for data analysts, engineers, and developers who need to perform ad-hoc analysis on structured semantic tables without manually writing complex SQL or Ibis code.

• Executes semantic model discovery via list_models() and get_model(name) to map field schemas.

• Supports advanced data manipulations, including group_by, aggregate, mutate, and filter operations.

• Implements a specialized multi-hop query pattern for robust data discovery, ensuring filter values are validated before execution to prevent null or incorrect results.

• Handles sophisticated analytical tasks like percentage-of-total calculations, window functions (running totals, moving averages, rankings), and categorical bucketing.

• Manages time-series data using custom truncation methods (Y, Q, M, W, D, h, m, s).

• Provides seamless integration with visualization backends including Altair, Plotly, and Plotext for automatic chart rendering.

• Adheres to a strict 'discovery-first' workflow to ensure accuracy, requiring documentation retrieval for query methods when encountering syntax errors.

• Always discover available model fields using get_model() before attempting any query_model() operation.

• Use the query_model() function with specific parameters: set get_chart=false for exploration queries to avoid unnecessary rendering, and get_chart=true for final, presentable outputs.

• When dealing with categorical or location-based filters, perform a count or list operation first to confirm exact data values, avoiding assumptions about IDs or codes.

• Utilize ibis.cases() for conditional logic (e.g., binning or custom labeling) using the plural syntax.

• The agent is constrained by the underlying semantic model definitions; if a method or column is not defined in the BSL schema, it cannot be inferred.

• For complex analytical requirements, refer to internal documentation topics such as windowing, indexing, or nested subtotals to maintain best practices in data transformation.