# Your events, queryable directly

`run_sql` is available both as an MCP tool and to the in-dashboard analyst. It is a real SELECT against your event store, not a canned report.

## events table columns

| Column | Type |
| --- | --- |
| `game_id` | String |
| `device_id` | String |
| `session_id` | String |
| `event_name` | String |
| `ts` | DateTime64(3, 'UTC') |
| `level` | String |
| `platform` | String |
| `game_version` | String |
| `country` | String, a two-letter country code, empty when unknown (see [country and device](https://ravensight.io/docs/platform-support/#country-device)) |
| `device_model` | String, empty when unknown |
| `os_version` | String, empty when unknown |
| `gpu` | String, empty when unknown |
| `campaign`, `adset`, `creative` | String, where the device was acquired, from its [attribution](https://ravensight.io/docs/dashboard/#typed-events); empty for a device with none |
| `payload` | String, arbitrary JSON |
| `props` | Map(String, String) of the payload's top-level keys, so `props['difficulty']` reads a property directly. Values are text: cast before comparing numerically. The [typed event](https://ravensight.io/docs/dashboard/#typed-events) keys read the same way, so `toUInt64OrNull(props['rs_amount'])` is a purchase's minor units; leave out rows where `mapContains(props, 'rs_invalid')`. |

## Rules

- **SELECT only.** A single `SELECT` or `WITH... SELECT` statement. Writes, DDL, and settings changes are rejected before the query runs.
- **No comments, extra statements, dollar signs or table functions.** `--`, `/* */`, `#`, and semicolons (beyond one optional trailing one) are all rejected, as is a `$` anywhere in the query and any table-function call such as `FROM name(...)`.
- **events only.** The only readable table is `ravensight.events`, plus any CTEs you define in the same query. Other table names, table functions, and cross-database reads are rejected.
- **The game filter is automatic.** Every reference to `events` is rewritten to a subquery scoped to your own `game_id` before it runs. Do not write your own `game_id` predicate: you cannot see or query another game's rows regardless.
- **Row cap.** Results are capped at 100 rows when usage metering against the prepaid balance is on, and at 200 rows where metering is off, no matter what `LIMIT` you write. The same cap applies to the analyst and to MCP.
- **Money has its own tool.** For revenue use `get_monetization`. If you must read purchases here, `props['rs_amount']` is integer minor units of `props['rs_currency']`, so group by currency, leave out rows with `rs_invalid`, and count a repeated `rs_transaction_id` once per device.
- **Query and time limits.** Queries are capped at 4,000 characters and run with `readonly=1` at the database level. A metered query gets 3 seconds of execution and reads at most 1,000,000 rows and 64 MB; with metering off the limit is 15 seconds.

## Example

Deaths by level, most first:

```
select level, count() as deaths
from events
where event_name = 'player_death'
group by level
order by deaths desc
```

Source: https://ravensight.io/docs/run-sql/
Last updated: 2026-11-15
