What data is needed - Auxia Docs

Auxia uses four kinds of first-party data. You don’t need all four to start — most teams begin with user attributes and user events, and add the rest over time.

Data	Describes	Example
User attributes	Who each user is	Country, plan, sign-up date, lifetime value
User events	What each user does	`page_viewed`, `added_to_cart`, `video_started`
Transaction events	What each user buys	Order ID, amount, currency, items purchased
Item attributes	The things users interact with	A product’s category, price, and discount; an offer’s start and end date

You don’t have to reshape your data to match the structures below. Auxia’s Transform stage maps your tables as they are — these examples show what Auxia looks for, so you know which tables to connect.

How Auxia uses this data

Qualification criteria — rules that decide which users are eligible for a treatment, such as “signed up in the last 30 days” or “viewed a product twice this week”.
Content personalization — inserting attributes into a treatment’s content, such as a user’s first name or the price of an item they viewed.
Treatment selection — giving the model context to pick the best treatment for each user.
Machine learning features — aggregations such as “logins per week” or “purchases in the last 30 days” that Auxia’s models learn from. Ingested data is ready to use as features from day one.

User attributes

User attributes describe the current state of each user — who they are, rather than what they did. Common examples:

Profile: country, language, age band, sign-up date
Account: subscription plan, loyalty tier, account status
Value: lifetime value, total orders, last purchase date
Technical: device type, operating system, app version

Each user attribute table needs:

Field	Required	Description
`user_id`	Yes	The primary user ID — the same ID you pass to the Get Treatments API
Attributes	Yes	One or more attributes describing the user
`update_timestamp`	Yes	When the attributes were last updated, so Auxia always uses the latest value

Attributes can be stored in either of two shapes. Auxia recognizes both automatically.

Attributes in columns

One row per user, one column per attribute.

user_id	country	plan	signup_date	lifetime_value	updated_at
u_1001	US	premium	2025-03-14	412.50	2026-10-01T08:00:00Z
u_1002	JP	free	2026-07-02	0.00	2026-10-01T08:00:00Z
u_1003	GB	premium	2024-11-20	1,280.00	2026-10-01T08:00:00Z

Attributes in rows

Several rows per user: one column holds the attribute name, another its value.

user_id	attribute_name	attribute_value	updated_at
u_1001	country	US	2026-10-01T08:00:00Z
u_1001	plan	premium	2026-10-01T08:00:00Z
u_1002	country	JP	2026-10-01T08:00:00Z
u_1002	plan	free	2026-10-01T08:00:00Z

User events

Events record what users do — one row per action, with the user, the action, and when it happened. They usually come from your analytics tool or clickstream data, across your website and apps.

Field	Required	Description
`user_id`	Yes	The user who performed the event
`event_name`	Yes	What happened, such as `sign_up`, `page_viewed`, or `added_to_cart`
`event_timestamp`	Yes	When it happened
Event properties	No	Context about the event, such as `page_url`, `product_category`, or `cart_value`
User properties	No	The user’s state at the time of the event, such as `subscription_status`

user_id	event_name	event_timestamp	channel	page_url
u_1001	page_viewed	2026-10-01T10:23:45Z	web	/products/trail-jacket
u_1002	added_to_cart	2026-10-01T11:45:32Z	app	/products/rain-shell
u_1001	sign_up	2026-10-01T12:15:20Z	app	—

If every row in a table is the same event (for example, a table of logins), you can give it an event name during setup instead of needing an event_name column. GA4, Firebase, Amplitude, Mixpanel, and Segment event exports are recognized automatically.

Transaction events

Transactions are events that record a purchase. They follow the same structure as user events, with properties that describe the order. Connecting them lets Auxia optimize for revenue and conversion, not just engagement.

user_id	event_name	event_timestamp	order_id	item_id	quantity	amount	currency
u_1001	order_completed	2026-10-01T14:02:11Z	ord_88412	sku_2231	1	149.00	USD
u_1001	order_completed	2026-10-01T14:02:11Z	ord_88412	sku_0457	2	38.00	USD
u_1003	subscription_renewed	2026-10-02T00:00:05Z	ord_88530	plan_premium	1	12.99	GBP

Include an item ID (such as item_id or sku) when you have one, so transactions can be linked to your item attributes.

Item attributes

Item attributes describe the things users interact with — products, offers, articles, videos, listings — rather than the users themselves. They give Auxia context about what each user is looking at or buying, so it can recommend similar items or the right offer. An item table has one row per item, keyed by an item ID that also appears in your events or transactions. It doesn’t need a user ID. Example: a retail product catalog

item_id	name	category	brand	price	discount_pct	launch_date	in_stock
sku_2231	Trail Jacket	Outerwear	Acme	149.00	20	2026-08-15	true
sku_0457	Wool Socks (2-pack)	Accessories	Acme	19.00	0	2025-11-01	true

Example: a promotions table

offer_id	offer_type	discount_pct	eligible_category	start_date	end_date
fall_outerwear_20	percent_off	20	Outerwear	2026-09-15	2026-10-31
free_shipping_50	free_shipping	0	All	2026-10-01	2026-12-31

Item tables connect through the same self-serve setup wizard as your other tables. They don’t need a primary user ID — see Entity tables in Map your data.

Reference: Auxia’s unified event schema

Auxia’s Transform stage maps every event source into one unified event schema. You don’t need to produce this structure yourself — it’s here for teams that send events directly with the Log Events API or want to know what Auxia stores.

Proto structure

syntax = "proto3";

import "google/protobuf/timestamp.proto";

message LogEventsRequest {
  // For any given Auxia customer, this should always be the same.
  // Required.
  string project_id = 1;

  // Unique ID for the user that can be joined to events and attributes.
  // Required.
  string user_id = 2;

  // Events for the user.
  // Required.
  repeated ExternalEventPb events = 3;
}

// Attributes of a single event.
message ExternalEventPb {
  // Name of the event.
  // Required.
  string event_name = 1;

  // Auxia uses this identifier to de-duplicate events for the same user.
  // Optional.
  string insert_id = 2;

  // Key-value pairs describing the event.
  // Optional.
  map<string, PropertyValuePb> event_properties = 3;

  // Key-value pairs describing the user.
  // Optional.
  map<string, PropertyValuePb> user_properties = 4;

  // The timestamp of the event.
  // Required.
  .google.protobuf.Timestamp client_event_timestamp = 5;

  // When the event was received by the server.
  // Optional.
  .google.protobuf.Timestamp server_received_timestamp = 6;

  // Identifies a user across signed-out and signed-in sessions.
  // Optional.
  string pre_login_temp_user_id = 7;

  // Optional.
  string session_id = 8;
  string country = 9;
  string region = 10;
  string city = 11;
  string ip_address = 12;
  string device_id = 13;
  string app_version_id = 14;
}

// Value corresponding to the property. Set exactly one.
message PropertyValuePb {
  oneof property_value {
    int64 long_value = 1;
    double double_value = 2;
    string string_value = 3;
    bool boolean_value = 4;
    .google.protobuf.Timestamp timestamp_value = 5;
  }
}

BigQuery schema

Column	Mode	Type	Description
`project_id`	REQUIRED	STRING	Unique identifier for a given Auxia customer
`user_id`	REQUIRED	STRING	Unique ID for the user
`event_name`	REQUIRED	STRING	Name of the event
`insert_id`	NULLABLE	STRING	Identifier for de-duplicating events
`event_properties`	REPEATED	RECORD	Key-value pairs describing the event (see below)
`user_properties`	REPEATED	RECORD	Key-value pairs describing the user (see below)
`client_event_timestamp`	REQUIRED	TIMESTAMP	When the event happened
`server_received_timestamp`	NULLABLE	TIMESTAMP	When the server received the event
`pre_login_temp_user_id`	NULLABLE	STRING	Identifies the user across sessions
`session_id`	NULLABLE	STRING	A single user session
`country`, `region`, `city`	NULLABLE	STRING	User location
`ip_address`	NULLABLE	STRING	IP address of the user
`device_id`	NULLABLE	STRING	The user’s device
`app_version_id`	NULLABLE	STRING	App version the event came from

Each event_properties and user_properties record has a required property_name and exactly one of long_value (INTEGER), double_value (FLOAT), string_value (STRING), boolean_value (BOOLEAN), or timestamp_value (TIMESTAMP).

Building properties in SQL (BigQuery)

CREATE OR REPLACE FUNCTION `<gcp-project-name>.<data-set>.create_properties`(property_name STRING, data_type STRING, column_value STRING)
RETURNS STRUCT<
    property_name STRING,
    long_value INT64,
    double_value FLOAT64,
    string_value STRING,
    boolean_value BOOL,
    timestamp_value TIMESTAMP
>
AS (
  CASE
    WHEN data_type = 'LONG' THEN STRUCT(
      property_name AS property_name, CAST(column_value AS INT64) AS long_value,
      CAST(NULL AS FLOAT64) AS double_value, NULL AS string_value,
      CAST(NULL AS BOOL) AS boolean_value, CAST(NULL AS TIMESTAMP) AS timestamp_value)
    WHEN data_type = 'DOUBLE' THEN STRUCT(
      property_name AS property_name, NULL AS long_value,
      CAST(column_value AS FLOAT64) AS double_value, NULL AS string_value,
      CAST(NULL AS BOOL) AS boolean_value, CAST(NULL AS TIMESTAMP) AS timestamp_value)
    WHEN data_type = 'BOOLEAN' THEN STRUCT(
      property_name AS property_name, NULL AS long_value,
      CAST(NULL AS FLOAT64) AS double_value, NULL AS string_value,
      CAST(column_value AS BOOL) AS boolean_value, CAST(NULL AS TIMESTAMP) AS timestamp_value)
    WHEN data_type = 'TIMESTAMP' THEN STRUCT(
      property_name AS property_name, NULL AS long_value,
      CAST(NULL AS FLOAT64) AS double_value, NULL AS string_value,
      CAST(NULL AS BOOL) AS boolean_value, CAST(column_value AS TIMESTAMP) AS timestamp_value)
    -- STRING, and anything else, is stored as a string.
    ELSE STRUCT(
      property_name AS property_name, NULL AS long_value,
      CAST(NULL AS FLOAT64) AS double_value, column_value AS string_value,
      CAST(NULL AS BOOL) AS boolean_value, CAST(NULL AS TIMESTAMP) AS timestamp_value)
  END
);

​How Auxia uses this data

​User attributes

​Attributes in columns

​Attributes in rows

​User events

​Transaction events

​Item attributes

​Reference: Auxia’s unified event schema