Getting Started
After connecting a data source (e.g., Google BigQuery), the Auxia Console guides you through two steps to connect your data: Explore and Mapping. These steps are the same regardless of which data connector you use.
Before proceeding, review the Source Data Requirements to ensure your tables are ready to be connected.
Step 1: Explore Datasets
After your data connection is validated, the wizard automatically discovers your datasets and tables.
- Ready tables pass all validation checks (partitioning, append support, change history) and can proceed to mapping.
- Not Supported tables have issues that need to be resolved (e.g., missing partitioning, unsupported configuration). The UI displays specific error messages for each not supported table.
Review the discovered tables, then click Continue with Mapping to proceed.
Step 2: Schema Mapping
Once your tables are validated, Auxia uses AI to automatically classify your table columns. 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
userIdto 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 theuserIdmatches 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: No. Auxia requires tables to be date-partitioned for efficient incremental reads. You can add partitioning to an existing table by recreating it:
CREATE TABLE `project.dataset.my_table_partitioned`
PARTITION BY DATE(event_timestamp)
AS SELECT * FROM `project.dataset.my_table`;
Q: Why are views not supported?
A: Auxia uses table-valued functions (e.g., BigQuery's APPENDS) for incremental data reads. These functions only work on native tables, not views.
Q: What does "append-based reads" mean? A: Append-based reads means Auxia only reads new rows added since the last run, rather than scanning the entire table. This is more efficient and cost-effective. Tables that add more than 1 TB per day must use this method.
Q: Can I use UPDATE or DELETE on my source tables?
A: No. Auxia's incremental reads rely on immutable append-only data. If you need to mutate data, maintain a separate table for Auxia that receives only appended rows.
Q: Some of my tables show as "Not Supported" during the Explore step. 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: Sync frequency depends on your configuration. Contact your Auxia point of contact for details on scheduling.