Data Model
Events, users, properties and retention
IForevents stores event data in ClickHouse, one project per tenant scope. The core concepts:
- Event: something a person did (
page_view,purchase,signup). Every event has a name, a type, a timestamp and properties. - User: a tracked person, keyed by the
custom_idyou send with identify, plus optional name, email, phone and properties. - Property: a key/value pair attached to an event or a user. Values are stored as strings.
- Event parent: the distinct event names seen in a project; the dashboard uses them for filters and top-event lists.
- Retention: how long raw events and users are kept. See Data retention.
Tables
| Table | Contents |
|---|---|
events | One row per tracked event, partitioned by month, ordered by project and time |
users | Tracked end users, keyed by custom_id within a project |
event_parents | Distinct event names per project with their counts |
projects, organizations | Tenancy; every row carries the organization it belongs to |
audit_log | Who changed what, per organization |
Fourteen materialized views precompute daily counts, per-user daily activity and property values so dashboards never scan raw events.
Event schema
| Field | Type | Set by | Notes |
|---|---|---|---|
uuid | UUID | server | Unique per stored event |
project_uuid, organization_uuid | UUID | server | Tenancy, from the project key |
user_uuid | UUID | server | The profile named by X-User-Id (or the address-derived fallback profile when the header is missing) |
parent_name | string | you | The event name (event_name at ingest) |
type | track, page_view, identify | you | Defaults to track |
created_at | datetime | server, or created_at in batch items | Event time |
properties | map of string to string | you | Flattened at ingest |
Property naming
Use snake_case keys and keep them stable across releases; the dashboard groups and filters by exact key. Put variants in values (plan: pro) rather than in event names.
Auto-collected properties
The Flutter SDK adds device brand and model, OS and version, app version and platform to every identify call, and the server stamps ingest time on events that carry none.
Isolation
Every query is scoped by the organization in the caller's session or project credentials; a project key can never read another project's data, and the dashboard only lists projects of the current organization.