Data model · Amplitude learning guide

By the end of this chapter

You can read the parts of an event record and what each is for.
You can decide whether a piece of information should be an event property or a user property.
You will understand how the "value at the time" behaviour of user properties affects analysis.

Four concepts

Concept	Meaning	Example	Closest Adjust equivalent
Event	A single action by the user, with a timestamp	`Product Viewed`, `Checkout Completed`	Event defined by an event token
Event property	The context of that action at that moment	`category = headphones`, `price = 49.9`	Callback / partner parameters
User property	A lasting attribute of the user; its latest value carries over to later events	`plan = premium`, `orders_count = 3`	No direct equivalent; attribution fields are closest
Group	The account or organisation the user belongs to	`company_id = 8812`	None

Anatomy of an event

Every event sent to Amplitude is a record like the one below. SDKs fill most of these fields themselves; you usually only provide the event name and properties.

Sample event record (simplified)

{
  "event_type": "Checkout Completed",      // what they did
  "time": 1762243200000,                      // when (ms)
  "user_id": "cust_88231",                  // who (ID in your system)
  "device_id": "8F3A2C1E-…",                // which device
  "platform": "iOS",                         // filled by the SDK
  "country": "Saudi Arabia",                // derived from IP
  "event_properties": {                       // context of this action
    "order_id": "ORD-5521",
    "revenue": 129.5,
    "currency": "SAR",
    "items_count": 3,
    "payment_method": "apple_pay"
  },
  "user_properties": {                        // user state at this moment
    "plan": "premium",
    "orders_count": 4,
    "acquisition_network": "Meta"         // example: source from an integration
  }
}

Read this record as a sentence: on 4 November, on iOS, while on the premium plan and as someone acquired via Meta, cust_88231 completed a 3-item order worth SAR 129.50 using Apple Pay. Every Amplitude chart is these sentences counted in different ways.

Verify

acquisition_network is a made-up example name. The real names of the fields that the Adjust integration sends to Amplitude are in the integration documentation (Chapter 7).

Event property or user property?

The rule is simple: does the information belong to that action or to that person? An order amount belongs to the order, so it is an event property. A subscription plan belongs to the person and applies to every later action, so it is a user property.

Information	Where it belongs	Reason
Category of the viewed product	Event property	Different on every view
Order amount	Event property	Specific to that order
Subscription plan	User property	The person's state until it changes
Total number of orders	User property (incremented)	The person's cumulative state
Acquisition channel (from Adjust)	User property	Assigned once to the person, slices all behaviour
Payment method	Event property (optionally also a "last payment method" user property)	Can change on every order
App language	User property (often collected by the SDK automatically)	A device/person setting

How user properties behave over time

Once a user property is set, it is stamped on every later event with that value until it is changed. The value stamped on an event is the value at the moment the event happened. That is how "did they buy while premium or while free?" gets answered correctly.

Same user, same event. Events after the plan change carry the new value; earlier events keep the old one.

Common mistake

Setting the user property after the event. If you send Subscription Started first and the plan update second when a user upgrades, that event still carries plan = free. Write the order explicitly in the tracking plan.

Ways to change a user property

SDKs offer several operations for user properties. The one you choose determines how the value accumulates over time.

Operation	What it does	When to use it
`set`	Overwrites the value	Plan, language, last payment method
`setOnce`	Sets only the first time, ignores later calls	First signup date, first acquisition channel
`add`	Increments/decrements a number	Order count, total spend
`append` / `prepend`	Adds an item to an array	Categories of interest
`unset`	Removes the property	Information that no longer applies

Why property types matter

Amplitude offers operations on a property based on its value type. For a value sent as a number you can take the sum, average and distribution. Send the same value as text and you can only filter for equality and group by it.

Limits analysis

"price": "49.9" is text, no average
"is_first_order": "yes" sent as "Yes", "true", "1" in different places
"category": "Headphones" on one platform, "headphones" on another

Open to analysis

"price": 49.9 is a number, sum and average work
"is_first_order": true one boolean type
"category": "headphones" lowercase everywhere, fixed list

Automatically collected information

SDKs add a set of fields to every event themselves: platform, OS and version, device model, app version, language, and country and city derived from IP. You don't need to send these as properties. Newer SDKs can also capture some events automatically, such as session start or page views (autocapture).

Verify

Which fields and events are captured automatically depends on the SDK, its version and its configuration. For clients with privacy requirements (for example, no IP or city collection), check the SDK documentation for how to turn these off.

Groups: account-level analysis

In B2B products the question is often "which company" rather than "which user". Groups tie users to an account and let charts count accounts instead of users: "How many companies created a report this week?"

Verify

Account-level analysis may be sold as a separate add-on in Amplitude. Check whether the client's plan includes it. Ryze's typical consumer mobile apps often don't need it.

Example: a small e-commerce model

Event	Event properties	User property updated with this event
`Signup Completed`	`method` (email, apple, google)	`signup_date` (setOnce)
`Product Viewed`	`product_id`, `category`, `price`	–
`Product Added to Cart`	`product_id`, `category`, `price`, `quantity`	–
`Checkout Started`	`cart_value`, `items_count`	–
`Checkout Completed`	`order_id`, `revenue`, `currency`, `payment_method`	`orders_count` (add 1), `last_order_date` (set)

Five events are enough for funnels, retention, basket analysis and first-vs-repeat order comparisons. Note that instead of one event per category, a single event with a category property is used.

Exercise

Take a client's Adjust event token list. For each event, decide: should it keep the same name in Amplitude, should several Adjust events merge into one Amplitude event plus a property (e.g. purchase_tier1, purchase_tier2 → Purchase + tier), and which information belongs to the person and should be a user property.