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

# How to query your data with SQL

> Write read-only ClickHouse SQL on your raw events in the Explorer, start from an example, and turn a query into a dashboard chart.

The Explorer runs read-only SQL on your project's raw events. Use it when a report or a dashboard does not answer your question.

## Part 1: Open the Explorer

**1. Open the SQL tab**

Click **Explorer** in the left navigation, then click **Data**. The **SQL** tab opens.

**2. Load an example**

Click **Examples** (or **load an example**) and pick a query. It goes into the query box.

**3. Run the query**

Change the query and click **Run query**. The results show below as a table.

You query the table `raw_events`. Each row is one event. For session counts, read the table `sessions` (one row for each session of the date range; see [Explorer](https://docs.manalens.dev/features/explorer.md#the-sessions-table)). Read fields in `context` and `properties` with `JSONExtractString()` or `JSONExtractFloat()`. See the [data catalog](https://docs.manalens.dev/data/catalog.md) for every column.

## Part 2: Useful queries

**Top custom events in the date range**

```sql theme={null}
SELECT event, count() AS events
FROM raw_events
WHERE type = 'track'
  AND toDate(original_timestamp) BETWEEN {{date_from}} AND {{date_to}}
GROUP BY event
ORDER BY events DESC
LIMIT 20
```

**Visitors by acquisition channel**

```sql theme={null}
SELECT JSONExtractString(context, 'channel_type') AS channel,
       uniqExact(anonymous_id) AS visitors
FROM raw_events
WHERE type = 'page'
  AND JSONExtractString(context, 'device') != 'bot'
GROUP BY channel
ORDER BY visitors DESC
```

**Revenue by plan**

```sql theme={null}
SELECT JSONExtractString(properties, 'plan') AS plan,
       sum(JSONExtractFloat(properties, 'revenue')) AS revenue
FROM raw_events
WHERE type = 'track' AND event = 'purchase'
GROUP BY plan
ORDER BY revenue DESC
```

`{{date_from}}` and `{{date_to}}` follow the date range in the page header. Use both or neither.

## Part 3: Know the limits

* Write one `SELECT` or `WITH` statement, without comments. Only `raw_events`, `sessions`, `session_events` and your own subqueries are allowed.
* A result has at most 200 rows. A query stops after 8 seconds.
* You can run 10 queries a minute, and a project can run 30.
* `raw_events` includes bot rows. Exclude them with `JSONExtractString(context, 'device') != 'bot'`.
* Use `uniqExact(message_id)` for exact event counts, because a client retry can repeat a row.

## Part 4: Save a query as a chart

The Explorer does not save queries. To keep one, open a dashboard, click **Add chart**, click **Blank chart**, paste the query into the **SQL query** box, name the columns to draw, and click **Save Chart**. See [How to build a custom dashboard](https://docs.manalens.dev/guides/custom-dashboard.md).

> [!TIP]
>
> From an AI tool, the MCP tool `execute_query` runs SQL with the same rules. It needs the `query:read` scope. See [MCP](https://docs.manalens.dev/mcp/overview.md).

## Related

* [Explorer](https://docs.manalens.dev/features/explorer.md): the full rules and limits.
* [Data catalog](https://docs.manalens.dev/data/catalog.md)
* [How to use Ask AI](https://docs.manalens.dev/guides/ask-ai.md): get a chart without writing SQL.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.