Core concepts

Poolstatis has exactly four primitives. Pick the right one and everything else follows.

Event#

An immutable fact — "X happened at time T". Signups, exports, purchases, page views. Events are append-only; they're never edited (except GDPR deletion by distinct_id).

Name them object.action, past tense, snake_case: checkout.completed, doc.exported.

Entity#

A mutable object with a current state — users, accounts, documents. Anything where you care about the latest value, not a stream of facts. A user's plan, an account's seat count, a document's status: entities, upserted when they change.

Rule of thumb: if it changes over time and you only care about the latest value, it's an entity property — not an event property.

Metric#

A declared measurement over events or entities, with a mandatory purpose. Metrics are the only thing the query layer references — never raw event names.

Funnel#

An ordered sequence of metrics with a goal. Because steps reference registered metrics, a funnel inherits the purpose of each step.

Identity#

distinct_id is the actor — the stable, authenticated user id from your product. Stability is what makes retention, funnels, and unique counts correct.