> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vigilos.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Ask AI

> Use natural language to query your data and get instant answers with interactive visualizations.

## Starting a Conversation

<Steps>
  <Step title="Open Ask AI">
    Click **Ask AI** in the sidebar to open the conversational analytics interface.
  </Step>

  <Step title="Select a semantic model">
    Use the model selector dropdown at the top of the chat to choose which semantic model the AI should use. The model determines which database, tables, and business definitions are available.
  </Step>

  <Step title="Type your question">
    Enter a question in plain English. The AI agent handles everything from schema lookup to query execution.
  </Step>
</Steps>

## Example Questions

Here are the types of questions you can ask:

| Question                                                     | What It Does                                                   |
| ------------------------------------------------------------ | -------------------------------------------------------------- |
| "What were the top 10 products by revenue last month?"       | Aggregates revenue by product with a date filter and limit     |
| "Show me daily active users over the past 30 days"           | Counts distinct users grouped by day with a date range         |
| "What is the average order value by country?"                | Computes an average measure grouped by a dimension             |
| "Compare this quarter's revenue to last quarter"             | Uses window functions or date arithmetic for period comparison |
| "Which customers placed orders in January but not February?" | Generates SQL with set operations (EXISTS / NOT EXISTS)        |

You do not need to know which tables or columns to use. The AI agent reads your semantic model's entity names, column descriptions, and measures to map your business question to the correct database structure.

## Understanding Results

Each response from the AI includes up to three parts:

<CardGroup cols={3}>
  <Card title="Chart" icon="chart-simple">
    An interactive visualization chosen by the AI based on your question. Bar charts for comparisons, line charts for trends, pie charts for proportions, and more.
  </Card>

  <Card title="Data table" icon="table">
    The raw result set displayed as a sortable table. You can inspect individual values and verify the data behind the chart.
  </Card>

  <Card title="AI explanation" icon="message">
    A natural language summary of what the agent found, highlighting key trends, outliers, or notable patterns in the results.
  </Card>
</CardGroup>

## Conversation History

The AI agent maintains context throughout a conversation. You can build on previous questions without repeating yourself:

* "Now break that down by region" - references the previous query's measure
* "Exclude refunded orders" - adds a filter to the previous result
* "Show that as a line chart instead" - changes the visualization type
* "What about the last 90 days?" - adjusts the date range

Starting a new conversation resets the context entirely.

## Visual Builder vs. SQL Mode

The AI agent automatically selects the best approach for your question:

<Tabs>
  <Tab title="Visual builder mode">
    Used for straightforward aggregation queries. The agent generates a structured configuration with dimensions, measures, filters, sorts, and chart settings. This mode covers questions like:

    * Group-by aggregations ("revenue by country")
    * Top-N queries ("top 10 customers")
    * Filtered counts ("orders this month")
    * Simple comparisons ("revenue by product category")
  </Tab>

  <Tab title="SQL mode">
    Used for complex analytical queries that require the full power of SQL. The agent writes raw SQL when the question involves:

    * **Window functions** - running totals, rankings, moving averages
    * **CTEs (Common Table Expressions)** - multi-step transformations
    * **Complex JOINs** - self-joins, cross joins, or multi-path joins
    * **Set operations** - UNION, EXCEPT, INTERSECT
    * **Subqueries** - correlated or nested queries
  </Tab>
</Tabs>

You do not need to specify which mode to use. The agent decides automatically based on the complexity of your question.

## Saving Results as Insights

When you get a result worth keeping, you can save it as an insight:

<Steps>
  <Step title="Click Save as Insight">
    After the AI returns results, click the **Save as Insight** button below the chart.
  </Step>

  <Step title="Name your insight">
    Give it a descriptive name like "Monthly Revenue by Region" or "Top Customers Q4".
  </Step>

  <Step title="Use it across the platform">
    Saved insights can be:

    * Added to **dashboards** as tiles in a drag-and-drop grid layout
    * Included in **reports** alongside narrative text
    * **Shared** with team members in your organization
    * **Scheduled** for automated delivery via Slack or email
  </Step>
</Steps>

<Tip>
  Save insights for any metric your team tracks regularly. This avoids re-asking the same question and ensures everyone sees consistent results.
</Tip>