Events & properties

Everything in Narrato is built on one primitive: the event. A page view, a sign-up, an invoice payment: each is an event with a name, a timestamp, who did it, and whatever context you attach.

Anatomy of an event

{
  "event_name": "signup_completed",
  "user_id": "user-42",
  "session_id": "b3c1…",
  "platform": "web",
  "properties": { "plan": "free", "referrer_campaign": "launch" }
}

Field	Meaning
event_name	What happened. Use stable, snake_case names, because they become the vocabulary you (and the assistant) query by.
user_id	Who did it. The SDK sends a persistent anonymous id until you call identify().
session_id	Groups activity into visits; the SDK manages this (30-minute inactivity window).
platform	Free-form (web, ios, backend, …), useful for filtering.
properties	Arbitrary JSON context, per event type.
timestamp / received_at	When it happened / when we received it. The server stamps received_at authoritatively.

The server also stamps every event with your project based on the write key that delivered it, so a client can never write into someone else’s project, whatever it puts in the payload.

Properties are JSON: query them with JSON_VALUE

properties is stored as a JSON document, not as flat columns. That keeps your schema flexible (new properties need zero setup), with one querying rule to know: extract values with JSON_VALUE before filtering or grouping on them.

-- Top plans chosen at signup, last 30 days
SELECT JSON_VALUE(properties, '$.plan') AS plan, COUNT(*) AS signups
FROM events
WHERE event_name = 'signup_completed'
  AND __time > CURRENT_TIMESTAMP - INTERVAL '30' DAY
GROUP BY 1
ORDER BY 2 DESC

Comparing properties directly (properties = '…', properties LIKE '…') fails with a type error. More SQL guidance in Querying your data.

Naming advice

• Events: verb-based and past tense reads well in every surface: signup_completed, report_shared, checkout_abandoned.
• Properties: keep values low-cardinality where you plan to group by them (plan: "free" groups nicely; a raw email address doesn’t). Read Privacy & PII before sending anything personal.
• Annotate as you go: the console’s Context page is a data dictionary the assistant reads on every question. A one-line description per event pays for itself immediately, and deprecated events can be marked so they stop polluting new analyses.