> ## 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.

# Insights

> Create, configure, and save data explorations as reusable insights for dashboards and reports.

## What Are Insights?

Insights are saved data explorations that serve as the building blocks for dashboards and reports. Each insight contains a query (either built visually or written as raw SQL), a chart configuration, and a result set. Once saved, an insight can be added to multiple dashboards and reports without duplicating the query logic.

<Info>
  Insights can be scoped to a specific connection and semantic model, or they can use standalone SQL against any connection.
</Info>

## Creating an Insight

Navigate to **Insights** in the sidebar and click **New Insight**. You can build your exploration using either the **visual builder** or the **SQL editor**.

### Visual Builder Mode

The visual builder lets you construct queries by selecting dimensions, measures, filters, and sorts from your semantic model without writing SQL.

<Steps>
  <Step title="Add dimensions">
    Dimensions are the columns you group by. Select one or more columns from your semantic model entities. For date columns, you can set a **granularity** to bucket values:

    | Granularity | Groups by             |
    | ----------- | --------------------- |
    | `day`       | Each calendar day     |
    | `week`      | Start of each week    |
    | `month`     | Start of each month   |
    | `quarter`   | Start of each quarter |
    | `year`      | Calendar year         |
  </Step>

  <Step title="Add measures">
    Measures define the values you want to aggregate. You can select pre-defined measures from your semantic model or create ad-hoc aggregations:

    | Aggregation      | Description            |
    | ---------------- | ---------------------- |
    | `SUM`            | Sum of all values      |
    | `AVG`            | Average of all values  |
    | `MIN`            | Minimum value          |
    | `MAX`            | Maximum value          |
    | `COUNT`          | Count of rows          |
    | `COUNT_DISTINCT` | Count of unique values |
  </Step>

  <Step title="Apply filters">
    Filters narrow the result set. Each filter targets a specific column and applies an operator:

    | Operator             | Example                                 |
    | -------------------- | --------------------------------------- |
    | `=`                  | status = 'active'                       |
    | `!=`                 | country != 'US'                         |
    | `>`, `<`, `>=`, `<=` | amount > 100                            |
    | `LIKE`               | name LIKE '%corp%'                      |
    | `IN`                 | region IN ('EMEA', 'APAC')              |
    | `NOT IN`             | status NOT IN ('cancelled', 'refunded') |
    | `IS NULL`            | email IS NULL                           |
    | `IS NOT NULL`        | phone IS NOT NULL                       |
  </Step>

  <Step title="Set sorts and limit">
    Add one or more sort rules to order your results. Each sort specifies a column and direction (`ASC` or `DESC`). Set a row limit to cap the number of results returned.
  </Step>
</Steps>

### SQL Editor Mode

Switch to the **SQL** tab to write raw SQL directly. The editor provides syntax highlighting and runs the query against the connection associated with your insight.

<Tip>
  Use the visual builder for exploratory analysis and the SQL editor when you need full control over the query, such as window functions, CTEs, or complex joins that go beyond what the visual builder supports.
</Tip>

## Configuring the Chart

After building your query, configure how the results are visualized. Every insight supports a chart type and chart options.

### Chart Types

| Type              | Best For                                                    |
| ----------------- | ----------------------------------------------------------- |
| **bar**           | Comparing categories side by side                           |
| **horizontalBar** | Categories with long labels that need more horizontal space |
| **stackedBar**    | Part-to-whole comparisons broken down by category           |
| **line**          | Trends over time with continuous data                       |
| **area**          | Volume trends over time, emphasizing magnitude              |
| **pie**           | Proportions of a whole (best with fewer than 8 segments)    |
| **funnel**        | Sequential stage drop-off (e.g., signup to purchase)        |
| **metric**        | Single KPI number displayed prominently                     |
| **table**         | Detailed data rows when exact values matter                 |

### Chart Configuration

| Option          | Description                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------- |
| **xAxis**       | Column to use for the horizontal axis (typically a dimension)                                                     |
| **yAxis**       | One or more columns for the vertical axis (typically measures). Multiple yAxis columns create multi-series charts |
| **groupBy**     | Column to split series by (creates separate lines, bars, or segments per group value)                             |
| **title**       | Chart title displayed above the visualization                                                                     |
| **showLegend**  | Toggle the legend on or off                                                                                       |
| **stacked**     | Stack bar or area series on top of each other instead of side by side                                             |
| **smooth**      | Use smooth curves for line and area charts                                                                        |
| **showArea**    | Fill the area under line charts                                                                                   |
| **colors**      | Custom color palette for the chart series                                                                         |
| **valueFormat** | Number formatting for axis labels and tooltips                                                                    |

## Saving and Reusing Insights

Click **Save** to store your insight with a name and optional description. Saved insights can be:

* **Added to dashboards** as widgets with optional visualization overrides
* **Embedded in reports** as chart or table blocks
* **Shared with teammates** via the sharing system with view or edit permissions

<Info>
  When you modify a saved insight, the changes propagate to all dashboards and reports that reference it. Widget-level visualization overrides (like a different chart type) are preserved.
</Info>

### Visibility

Insights start as **private** - only visible to you. You can share them with specific users or your entire organization. See [Sharing & Collaboration](/features/sharing) for details on access controls.