> ## Documentation Index
> Fetch the complete documentation index at: https://forest-chore-open-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Charts

> Visualize your data with KPI cards, time-based trends, distributions, and more.

**Charts** in Forest let you build visual data representations directly from your collections, without writing custom code. Use them to monitor KPIs, track trends, and create dashboards your operations team can act on.

Charts can be displayed in two places:

* The **Dashboard** tab, a shared dashboard visible to your team.
* The **Analytics** tab of a specific record, charts scoped to a single record's data.

## Chart types

Forest supports six chart types:

| Type             | Description                                               | Example                            |
| ---------------- | --------------------------------------------------------- | ---------------------------------- |
| **Single value** | Displays one key metric as a large number                 | Total customers, MRR               |
| **Repartition**  | Pie or donut chart showing distribution across categories | Customers by country, Paid vs Free |
| **Time-based**   | Line or bar chart showing a metric over time              | Signups per month                  |
| **Percentage**   | Displays a metric as a percentage                         | % paying customers                 |
| **Objective**    | Progress bar showing actual vs target                     | Orders vs monthly goal             |
| **Leaderboard**  | Ranked list showing top N items                           | Companies by transaction volume    |

<Info>
  For Repartition charts, only the top 5 categories are shown individually. All others are grouped into a 6th "Other" category.
</Info>

## Creating a chart

1. Enable **Layout Editor** mode by clicking the toggle in the top navigation.
2. Navigate to the **Dashboard** tab (or the Analytics tab of a record).
3. Click **Add a new chart**.
4. Enter a **name** and optional **description**.
5. Select a **chart type**.
6. Configure the chart data source (see below).
7. Save and exit Layout Editor mode.

### Simple mode (UI-based)

In **Simple mode**, configure your chart by selecting:

* **Collection**, which data source to query.
* **Aggregate function**, `count`, `sum`, `average`, `min`, `max`.
* **Group by field**, the dimension to group results by.
* **Time frame**, for time-based charts: day, week, month, or year.
* **Filters**, optional conditions to restrict which records are included.

### Query mode (SQL)

For advanced analytics, use **Query mode** to write custom SQL directly.

<Warning>
  Query mode is only available for SQL databases. For security reasons, only `SELECT` queries are allowed.
</Warning>

Each chart type expects specific column names in the query result:

| Chart type               | Required columns              |
| ------------------------ | ----------------------------- |
| Single value             | `value`                       |
| Single value with growth | `value`, `previous`           |
| Repartition              | `key`, `value`                |
| Time-based               | `key`, `value`                |
| Objective                | `value`, `objective`          |
| Leaderboard              | `key`, `value` (with `LIMIT`) |

**Example, Single value:**

```sql theme={null}
SELECT COUNT(*) AS value
FROM customers;
```

**Example, Repartition:**

```sql theme={null}
SELECT status AS key, COUNT(*) AS value
FROM orders
GROUP BY status;
```

**Example, Time-based:**

```sql theme={null}
SELECT DATE_TRUNC('month', created_at) AS key, COUNT(*) AS value
FROM signups
GROUP BY key
ORDER BY key;
```

**Example, Leaderboard:**

```sql theme={null}
SELECT companies.name AS key, SUM(transactions.amount) AS value
FROM transactions
JOIN companies ON transactions.beneficiary_company_id = companies.id
GROUP BY key
ORDER BY value DESC
LIMIT 10;
```

## Record-specific analytics

Charts can also be scoped to a single record. When placed in the **Analytics** tab of a collection:

* In **Query mode**, use `{{recordId}}` to inject the current record's ID into your SQL query.
* In **API mode**, the `record_id` is automatically passed in the HTTP body.

**Example:**

```sql theme={null}
SELECT DATE_TRUNC('month', transactions.created_at) AS key, SUM(transactions.amount) AS value
FROM transactions
WHERE transactions.company_id = {{recordId}}
GROUP BY key
ORDER BY key;
```

A chart configured this way works for all records in the collection.

## Managing charts

In **Layout Editor** mode:

* **Move** charts by dragging them on the dashboard.
* **Resize** charts to fit your layout.
* **Edit** a chart's configuration by clicking the pencil icon.
* **Delete** a chart by clicking the trash icon.