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

# Reports

> Create narrative-driven reports with rich text, charts, and data visualizations in a document layout.

## Reports vs Dashboards

Dashboards are grid-based layouts optimized for at-a-glance monitoring with multiple widgets updating in real time. Reports are document-style layouts designed for narrative analysis - they combine rich text explanations with embedded charts, tables, and KPI numbers to tell a data story from top to bottom.

Use **dashboards** when your audience needs a live, interactive overview. Use **reports** when you need to present findings with context, commentary, and a deliberate reading order.

## Creating a Report

<Steps>
  <Step title="Start a new report">
    Navigate to **Reports** in the sidebar and click **New Report**. Enter a name, optional description, and choose an icon (emoji) to identify it.
  </Step>

  <Step title="Add blocks">
    Build your report by adding blocks. Each block is a content element - a heading, paragraph of text, chart, table, KPI number, or divider. Blocks are organized into rows and positioned on a flexible grid.
  </Step>

  <Step title="Arrange the layout">
    Drag blocks to reorder them and resize to control width. Place blocks side by side or stack them full-width.
  </Step>

  <Step title="Configure and save">
    Set the report theme and visibility, then click **Save**.
  </Step>
</Steps>

## Block Types

### Heading

A text heading to structure your report into sections.

| Property  | Description                                                      |
| --------- | ---------------------------------------------------------------- |
| **text**  | The heading text                                                 |
| **level** | Heading size: `1` (H1, largest), `2` (H2), or `3` (H3, smallest) |

### Text

A rich text block powered by a TipTap editor. Supports markdown formatting including bold, italic, lists, links, and code blocks. Use text blocks to provide context, explain methodology, or narrate findings.

### Chart

A data visualization block that renders a chart from one of three data sources:

1. **Insight reference** - select a saved insight to reuse existing query logic
2. **Inline exploration** - define a semantic model query directly in the block (dimensions, measures, filters, sorts)
3. **Raw SQL** - write a SQL query against any of your database connections

Each chart block has its own chart configuration:

| Option      | Description                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------- |
| **type**    | `bar`, `horizontalBar`, `stackedBar`, `line`, `area`, `pie`, `funnel`, `metric`, or `table` |
| **xAxis**   | Column for the horizontal axis                                                              |
| **yAxis**   | One or more columns for the vertical axis                                                   |
| **groupBy** | Column to split series by                                                                   |
| **options** | Title, legend, stacking, smoothing, colors, value format                                    |

### Big Number

A prominent single KPI display, ideal for highlighting key metrics at the top of a report.

| Property        | Description                                 |
| --------------- | ------------------------------------------- |
| **valueColumn** | The column containing the metric value      |
| **format**      | `number`, `currency`, or `percentage`       |
| **prefix**      | Text before the value (e.g., "\$")          |
| **suffix**      | Text after the value (e.g., "users")        |
| **decimals**    | Number of decimal places                    |
| **comparison**  | Compare to a previous period to show change |
| **breakdown**   | Break the metric down by a dimension        |

Like chart blocks, big number blocks can source their data from a saved insight, inline exploration, or raw SQL.

### Table

A data table block that displays rows and columns. Supports the same three data sources as chart blocks. Use table blocks when exact values matter more than visual trends.

### Divider

A visual separator between sections of your report.

| Property  | Description                                       |
| --------- | ------------------------------------------------- |
| **style** | `line` (horizontal rule) or `space` (empty space) |
| **size**  | `sm` (small), `md` (medium), or `lg` (large)      |

## Layout

Reports use a flexible grid layout. Drag blocks to reorder them and resize to control width. Place blocks side by side or stack them full-width.

<Tip>
  Place related KPIs in a row of big number blocks across the top of your report, each spanning a few columns, to create a summary dashboard strip before diving into detailed analysis below.
</Tip>

## Data Sources

Chart, table, and big number blocks can pull data from three sources:

<AccordionGroup>
  <Accordion title="Saved Insight">
    Reference a saved insight. The block uses the insight's query and results. When the insight is updated, the report reflects the change automatically.

    This is the recommended approach when the same query is used across multiple dashboards and reports.
  </Accordion>

  <Accordion title="Inline Exploration">
    Define a semantic model query directly in the block. Select dimensions, measures, filters, and sorts without creating a separate saved insight.

    Use this for one-off visualizations that are specific to this report and unlikely to be reused elsewhere.
  </Accordion>

  <Accordion title="Raw SQL">
    Write a SQL query and associate it with a database connection. The query runs directly against the connection when the report is viewed.

    Use this when you need full SQL control, such as window functions, CTEs, or queries that span tables not covered by a semantic model.
  </Accordion>
</AccordionGroup>

## Report Settings

| Setting          | Description                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------ |
| **Theme**        | `light`, `dark`, or `auto` (follows system preference)                                     |
| **Visibility**   | `private` (only you), `organization` (all org members), or `public` (anyone with the link) |
| **Public token** | When visibility is `public`, a unique token URL is generated for unauthenticated access    |

<Warning>
  Public reports expose all data in every block to anyone with the link. Review all blocks for sensitive information before setting visibility to public.
</Warning>