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

# SQL access

> Query your raw events with SQL in the Explorer, in SQL dashboard charts, or from an AI tool through the MCP server.

ManaLens keeps every event in one table, `raw_events`. You can read it with ClickHouse SQL in three places. Every query reads only the current project.

| Where | Who | Limits |
| - | - | - |
| [Explorer](https://docs.manalens.dev/features/explorer.md), **SQL** tab | Project members (owner, admin, editor) | 200 rows, 8 seconds |
| SQL charts on a [dashboard](https://docs.manalens.dev/features/dashboards.md) | Members who can edit dashboards | Same rules as the Explorer |
| [MCP server](https://docs.manalens.dev/mcp/overview.md), `execute_query` | An API key or OAuth app with the `query:read` scope | 200 rows; same budgets as the Explorer |

> [!NOTE]
>
> There is no direct database connection, BI connector or scheduled export to your own warehouse. Use the Explorer or the MCP server to read rows. Contact support for a full data export.

## The `raw_events` table

| Column | Type | Description |
| - | - | - |
| `anonymous_id` | String | Persistent visitor ID. Empty before consent in consent mode. |
| `session_id` | String | Client session ID |
| `user_id` | String | Identified user ID, if any |
| `channel` | String | Event origin: `web`, `app`, `server`, `stripe`, `paddle`, `dashboard` |
| `type` | String | `page`, `track`, `identify` and billing event types |
| `event` | String | Custom event name (`track`) |
| `context` | String (JSON) | Page or app context, campaign fields, country, device, OS, browser, locale, `channel_type` |
| `properties` | String (JSON) | Custom event properties, or traits on `identify` |
| `version` | String | Envelope version |
| `original_timestamp` | DateTime64 | When the event happened |
| `received_at` | DateTime64 | When the collector received it |
| `message_id` | String | Unique event ID |

See [common fields](https://docs.manalens.dev/data/events/common.md) for every key in `context`.

## Read JSON fields

`context` and `properties` are JSON strings. Use the ClickHouse JSON functions:

```sql theme={null}
SELECT
  JSONExtractString(context, 'page', 'path') AS path,
  JSONExtractString(context, 'country') AS country,
  JSONExtractFloat(properties, 'revenue') AS revenue
FROM raw_events
WHERE type = 'track' AND event = 'purchase'
LIMIT 100
```

## Count correctly

* **Exclude bots.** `raw_events` keeps bot rows. Add `JSONExtractString(context, 'device') != 'bot'`.
* **Remove retries.** A client retry can store a row twice. Count events with `uniqExact(message_id)`.
* **Count visitors** with `uniqExact(anonymous_id)` and `anonymous_id != ''`.
* **Use the date range.** `{{date_from}}` and `{{date_to}}` follow the date range in the page header.

```sql theme={null}
SELECT
  toDate(original_timestamp) AS day,
  uniqExactIf(anonymous_id, anonymous_id != '') AS visitors,
  uniqExactIf(message_id, type = 'page') AS page_views
FROM raw_events
WHERE toDate(original_timestamp) BETWEEN {{date_from}} AND {{date_to}}
  AND JSONExtractString(context, 'device') != 'bot'
GROUP BY day
ORDER BY day
```

## Rules

Queries are read-only: one `SELECT` or `WITH` statement over `raw_events` and your own subqueries. Other tables, table functions and `SETTINGS` or `FORMAT` clauses are refused. See [Explorer limits](https://docs.manalens.dev/features/explorer.md#limits) for the full list.

## Related

* [SQL Explorer guide](https://docs.manalens.dev/guides/sql-explorer.md)
* [Metrics](https://docs.manalens.dev/data/metrics.md) for how the built-in reports count


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