Map your data - Auxia Docs

Every self-serve connector includes a mapping step, where you confirm what each column in your data means. This page is the reference for that step. For the full setup flow, see your connector’s setup guide — BigQuery, Amazon S3, or Google Cloud Storage. Before you start, review the Source data requirements.

Schema mapping

Auxia uses AI to classify your table columns automatically. This step tells Auxia what each column in your data represents — which column is the user identifier, which is the event timestamp, which columns are properties, and so on. Getting this right ensures accurate personalization and model performance. The mapping directly determines how Auxia builds user profiles, trains ML models, and delivers personalized treatments.

Understanding the Primary User ID

For user-level tables (events, attributes, transactions), the most important mapping is the user_id — the column that uniquely identifies a user across your data.

Not every table needs a user_id. Entity tables (e.g., product catalogs, content libraries, location data) describe things rather than users and need not have a user ID mapped.

Why it matters: The primary user ID is how Auxia knows which user to serve a treatment to. When Auxia delivers a recommendation on your app, website, email, push notification, or any other channel, it uses this ID to look up the right user and their profile. When the user ID is mapped correctly, Auxia accurately matches each user to their profile and delivers the right treatment. The simplest way to think about it: the primary user ID you map here should match the userId you pass to the Get Treatments and Log Treatment Interactions APIs. This is how Auxia connects your data (attributes, events, transactions) to the right user when those API calls are made. The primary user ID is the single key that connects everything in Auxia. It links a user’s attributes (who they are), events (what they do), and treatments (what Auxia recommends to them) into one unified profile. Specifically:

Serve treatments across channels — When your app or messaging platform requests a treatment for a user, it passes the userId to the Get Treatments API. Auxia uses that ID to match the user to their profile, run qualification rules, and return the right treatment. A correct ID ensures the right user receives the right treatment across all channels.
Close the feedback loop — When a user interacts with a treatment (views, clicks, dismisses), your app logs that interaction via the Log Treatment Interactions API using the same userId. When the userId matches across API calls and connected data, Auxia can accurately attribute interactions and continuously improve recommendations.
Build user profiles — All user attributes and behavioral data are aggregated under this ID. A correct mapping ensures Auxia builds accurate, unified profiles for each user.
Train ML models — Auxia’s models learn patterns per user. Accurate user IDs allow Auxia’s models to learn genuine per-user patterns, producing reliable predictions.
Target and qualify users — Qualification rules (e.g., “users who signed up in the last 30 days”) depend on the user ID to match the right users. A correctly configured ID ensures qualification rules match the right users to the right treatments.
Personalize content — Dynamic content insertion (e.g., “Hi {{first_name}}”) relies on looking up attributes by user ID. Correct mapping enables personalized content to resolve accurately for each user.
Measure outcomes — Engagement and conversion metrics are tracked per user. Correct user IDs ensure reliable engagement metrics and trustworthy A/B test results.

What makes a good primary user ID:

Characteristic	Why it matters
Unique per user	Each value maps to exactly one real person. Shared IDs (e.g., household IDs) will merge distinct users into one profile.
Stable over time	The ID should not change when a user updates their profile, switches devices, or re-authenticates. Session IDs or temporary tokens are not suitable.
Consistent across tables	The same user must have the same ID in your events table, attributes table, and any other tables you connect. This is how Auxia joins data across sources.
Non-PII preferred	Use internal identifiers (e.g., `user_id`, `customer_id`, UUID) rather than email addresses or phone numbers, to reduce PII exposure.

Common examples:

Good primary user ID	Avoid using as primary user ID
`user_id` (internal numeric/UUID)	`email` (can change, PII)
`customer_id` (CRM identifier)	`device_id` (one user, multiple devices)
`member_id` (loyalty program ID)	`session_id` (changes every session)
`uid` (Firebase/analytics ID)	`ip_address` (shared, not stable)

Entity Type Reference

The entity types you need to map depend on the kind of table you’re connecting. Below are the required and optional mappings for each table type.

Event Tables

Entity Type	Required?	Description
`user_id`	Required	The column that uniquely identifies the user who performed the event. This is the ID Auxia uses to serve treatments across all channels. See Understanding the Primary User ID.
`event_timestamp`	Required	When the event occurred. Used for time-based feature creation (e.g., “events in last 7 days”), model training windows, and incremental reads.
`event_name`	Required	The name or type of the event (e.g., `page_view`, `purchase`, `sign_up`). Auxia uses event names to create behavioral features and define qualification criteria.
`event_property`	Optional	Event-level properties (e.g., `cart_value`, `page_url`, `product_category`). Used to create granular behavioral features and enrich event context for the model.
`user_property`	Optional	User-level properties embedded within event rows (e.g., a `user_properties` nested field in GA4). Used for real-time user context at the time of the event. Distinct from standalone user attributes.

User Attributes Tables

Entity Type	Required?	Description
`user_id`	Required	The column that uniquely identifies the user. Must be the same identifier used across all your tables and in your Get Treatments API calls. See Understanding the Primary User ID.
`user_attribute`	Required	User-level properties that describe the state of the user — e.g., `subscription_status`, `country`, `sign_up_date`, `lifetime_value`. These are used for qualification rules, content personalization, and ML features.
`update_timestamp`	Required	The timestamp at which the user’s attributes were last updated. Auxia uses this for incremental reads and to ensure it always has the most recent snapshot of each user’s profile.

Entity Tables (non-user)

Entity tables describe things rather than users (e.g., product catalogs, content libraries, location data). These tables do not require a user_id mapping. The required mappings depend on the specific table structure.

Schema Type Classification

The AI also identifies the schema type of each table — what analytics platform or data structure it follows. This helps Auxia apply the correct parsing logic automatically.

Schema Type	UI Label	Description
GA4 Events	GA4 Events	Google Analytics 4 event export tables
GA4 Intraday	GA4 Intraday	GA4 intraday (streaming) event tables
Firebase Events	Firebase Events	Firebase Analytics event tables
Amplitude Events	Amplitude Events	Amplitude event export tables
Mixpanel Events	Mixpanel Events	Mixpanel raw event data
Segment Events	Segment Events	Segment event warehouse tables
Generic Events	Other: User Events	Custom event tables not matching a known analytics platform
Columnar Attributes	Other: User Attributes	User attributes stored as columns (one row per user, attributes as columns)
Row-based Attributes	Other: User Attributes	User attributes stored as key-value rows (multiple rows per user)
GA4 User Attributes	GA4 User Attributes	GA4 user-scoped dimension tables

Correcting Mappings

You can override any AI classification:

Find the column you want to correct.
Click the entity type dropdown and select the correct type.
The AI will automatically re-classify related columns based on your correction — for example, if you reclassify a column as user_id, the AI may update its classification of other identifier-like columns.

Review all mappings carefully before proceeding, paying special attention to user_id, event_timestamp, and event_name — these are the foundation of Auxia’s data model.

Troubleshooting & FAQ

Table & Data Issues

Q: My table doesn’t have partitioning. Can I still use it? A: The wizard flags unpartitioned tables — see Date partitioning for why. To add partitioning to an existing BigQuery table, recreate it:

CREATE TABLE `project.dataset.my_table_partitioned`
PARTITION BY DATE(event_timestamp)
AS SELECT * FROM `project.dataset.my_table`;

Q: Can I connect a view? A: Yes, with trade-offs — see Native tables preferred over views. Q: What does “append-based reads” mean? A: Auxia reads only the rows added since the last run instead of scanning the whole table. See Append-based reads for large tables. Q: Can I use UPDATE or DELETE on my source tables? A: No — see Append-only data. Q: Some of my tables show as “Not Supported” or “Blocked” during setup. What does this mean? A: Not Supported tables have validation issues that prevent connection. Common reasons include:

Missing partitioning — The table is not partitioned or uses yearly partitions.
Append not supported — The table’s configuration doesn’t support incremental read functions.

The UI displays the specific error for each not supported table. Fix the underlying issue and re-run validation.

Schema Mapping

Q: The AI mapped the wrong column as user_id. How do I fix it? A: Click the entity type dropdown on the column and select the correct one. The user_id mapping is foundational — it determines how Auxia builds user profiles, trains ML models, and delivers personalization. Verifying the user_id mapping before proceeding ensures accurate profiles, reliable predictions, and correct targeting. Q: My table has multiple ID columns (e.g., user_id, device_id, session_id). Which one should be user_id? A: Choose the column that uniquely and persistently identifies a real person — typically an internal user ID or customer ID from your CRM. Avoid device IDs (one user can have multiple devices) and session IDs (change every session). The user ID must be consistent across all tables you connect so Auxia can join data correctly. It should also be the same userId you pass to the Get Treatments and Log Treatment Interactions APIs. Q: The AI mapped my columns incorrectly. Can I fix it? A: Yes. Click the entity type dropdown on any column and select the correct type. The AI will re-classify related columns based on your correction. Q: What schema types does Auxia recognize? A: Auxia’s AI can classify tables as: GA4 Events/Intraday, Firebase Events, Amplitude Events, Mixpanel Events, Segment Events, Generic Events, Columnar Attributes, Row-based Attributes, and GA4 User Attributes.

General

Q: How often does Auxia sync data? A: It depends on the connector — see When will my data show up?

​Schema mapping

​Understanding the Primary User ID

​Entity Type Reference

​Event Tables

​User Attributes Tables

​Entity Tables (non-user)

​Schema Type Classification

​Correcting Mappings

​Troubleshooting & FAQ

​Table & Data Issues

​Schema Mapping

​General

Schema mapping

Understanding the Primary User ID

Entity Type Reference

Event Tables

User Attributes Tables

Entity Tables (non-user)

Schema Type Classification

Correcting Mappings

Troubleshooting & FAQ

Table & Data Issues

Schema Mapping

General