Glossary

Quick reference for terms used across the Pug docs, dashboard, SDKs, and API.

Term	Definition
Organization	Top-level tenant; has members, billing, and email config. See Core concepts.
Project	Data boundary; owns events, profiles, and dashboards. All analytics are project-scoped.
API key	Project-scoped credential. SDK keys are write-only; shared keys enable server-side reads.
Event	A named occurrence with properties and a timestamp. The atomic unit of analytics data.
Well-known event	Standard event name with a typed protobuf schema (e.g. `purchase`, `page_view`).
Custom event	Any event name not in the well-known registry. Accepted without schema validation.
Profile	A user record with an external ID and traits. Created on `identify()`.
Anonymous profile	Profile created before `identify()` — tied to device/session, not a known user.
Session	A group of events within a single visit. Managed automatically by SDKs.
Identify	SDK call linking anonymous activity to a known user ID. `identify('user-123', { email: '…' })`.
Alias	Server-side merge of two profile IDs into one. Used for pre/post-signup ID unification.
Trait	A key-value property on a profile, set via `identify()`. e.g. `plan: 'pro'`.
Auto-property	Property prefixed with `$`, attached automatically by SDK or server. e.g. `$geo.country`.
Insight	An analytics query spec: events, filters, time range, aggregation, breakdown.
Query spec	The JSON/Protobuf definition of an insight query. Powers charts, KPIs, and API responses.
Dashboard	A saved grid of insight and markdown tiles. Project-scoped.
Tile	One cell on a dashboard — either an insight chart or markdown content.
Funnel	Insight visualization showing step-by-step conversion through an event sequence.
Cohort	Group of users who performed a starting event in the same time period. Used in retention.
Conversion window	Max time allowed between funnel steps. e.g. 7 days.
Granularity	Time bucket size for queries: hour, day, or week.
Breakdown	Splitting query results by a property dimension. e.g. by country or plan.
Connect RPC	Protobuf RPC framework used by all Pug APIs. Supports Connect, gRPC, and gRPC-Web.
Principal	Auth identity — either a Customer (JWT) or Project (API key).
Protovalidate	Request validation layer applied to all RPC payloads at the interceptor.
BatchCreate	The sole event ingestion RPC. Sends one or more events in a single call.
JetStream	NATS persistence layer used for the async event and profile pipeline.
ClickHouse	Column-oriented database used for event storage and analytics queries.
NATS	Message queue connecting ingestion to async workers (enrichment, profiles).
NATS worker	Background process consuming from NATS — event enrichment and profile writes.
Full-reconcile upsert	Dashboard tile mutation model — the request payload is the complete desired tile set.
Sampling rate	SDK option to keep only a fraction of events (0–1). Used to reduce volume on high-traffic sites.
dryRun	SDK option to log events without sending. For development only.

Glossary

Further reading