Overview

The Query Builder is the central hub for creating and customizing dashboard visualizations. While you can manually configure every aspect of a chart, the AI-powered interface allows you to build complex queries using natural language.

This widget bridges the gap between your questions and the underlying data structure. It automatically translates your intent into aggregations, groupings, and filters, while recommending the most effective visualization for your data.

Using AI in the Query Builder

The Query Builder features a dedicated AI input at the top of the configuration panel. This is the fastest way to start a new visualization or overhaul an existing one.

1. Open a dashboard and click the **Settings** icon on any panel to open the Query Builder.
2. Locate the **Generate with AI** input field.
3. Type your request in plain English.
4. Press **Enter** or click **Generate**.
5. The AI populates the **Query** and **Chart** tabs with the necessary logic.
6. Click **Save** to apply the changes to your dashboard.

Natural Language Query Examples

The AI understands context and can handle multi-step logic. Here are some ways to phrase your requests:

  • Simple Aggregations: “Total sales for this year”
  • Grouped Data: “Product count by category and status”
  • Time-based Trends: “Monthly revenue for the last 6 months as a line chart”
  • Filtered Results: “Top 10 brands by average price where stock is greater than 100”
  • Comparative Analysis: “Compare sales between ‘Electronics’ and ‘Home’ categories”

Chart Recommendations

When you generate a query, the AI doesn’t just fetch data; it selects a visualization style that best represents that data structure.

  • Pie/Donut Charts: Recommended for showing parts of a whole or distributions (e.g., “Sales by category”).
  • Line/Area Charts: Recommended for trends over time (e.g., “Daily signups this week”).
  • Bar/Column Charts: Recommended for comparing discrete categories or rankings (e.g., “Top performing regions”).
  • Tables: Recommended when you need to see raw values or many dimensions at once.

You can always override these recommendations by switching to the Chart tab and selecting a different type manually.

Iterating and Refining

Rarely is a query perfect on the first try. The Query Builder supports an iterative workflow to help you dial in the details.

The AI Chat Interface

Click the Iterate with AI [badge:Beta|warning] icon next to the generate button to open the full-screen chat. This allows you to refine the existing query without starting over. You can say things like:

  • “Now filter this by the ‘North’ region.”
  • “Change the grouping from monthly to weekly.”
  • “Sort the bars from highest to lowest.”

Manual Fine-Tuning

The AI-generated values are fully editable. You can switch between tabs to make precise adjustments:

  • Query Tab: Modify the QL code, add specific where clauses, or change the limit.
  • Chart Tab: Adjust colors, labels, and specific visualization settings.

Tips for Success

**Be Specific:** Instead of "Show sales," try "Sum of price for all orders in the last 30 days." Using field names that exist in your data helps the AI be more accurate.

**Automatic Mapping:** When you use terms like "average," "total," or "count," the AI automatically maps these to `@avg()`, `@sum()`, and `@count()` functions in the Query tab.

**Complex Filters:** If the AI struggles with a complex filter, try breaking it down. Generate the base query first, then use the **Iterate with AI** chat to add filters one by one.

[try:/dashboard|Open Dashboards|database]