• A table becomes either a user schema or an event schema.
• The columns in that table become user properties or event attributes, depending on which kind of schema the table belongs to.

​

How a Warehouse Schema Works

​

How Users Are Matched

​

Set the Event Look-Back Window

​

Create a User Schema

1. On the sidebar menu in MoEngage, click Settings. The Settings page appears.
2. Under Data, click Warehouse Schema. The Warehouse schema page appears.
3. Select your connection from the dropdown beside the page title.
4. In Max event look-back, enter the number of days of event history MoEngage should read from this warehouse. The default is 60 days. For more information, refer to Set the Event Look-Back Window.
5. Click Create user schema. The Create user schema page appears.

​

Step 1: Source and Format

1. User schema name: Enter a name for the schema. Use something recognisable, because this name identifies the schema on the Warehouse schema page and in error messages when a segment fails.
2. Connection: This is pre-filled with the connection you opened the page for. Only one user schema is permitted per connection, so this cannot be changed here.
3. Schema/Dataset: Select the schema or dataset that holds your user master table. On BigQuery, this is your dataset. The list is populated from the connection.
4. Table: Select your user master table. The list is populated from the schema or dataset you selected. All the user IDs you want to segment on must be in this single table. MoEngage cannot combine user IDs from two tables, so pick the table that holds the complete set.
5. Columns for preview: Select the columns you want to see in the preview. Select only the columns you need to recognise the table. Every preview runs a live query against your warehouse, so previewing columns you do not need costs you time and money. Select all is capped at the first 5,000 columns and is not recommended.
6. Click Preview. MoEngage queries your warehouse and displays up to the top 100 rows for the columns you selected. Check the values before continuing. A preview that returns unexpected data usually means the wrong table was selected, which is far cheaper to fix now than after the mapping is done.
7. Click Next. The Mapping step appears.

​

Step 2: Mapping

1. User identifier: Select the column that holds your user ID. MoEngage matches the values in this column against the customer ID on existing MoEngage users, which is how a warehouse row becomes a targetable user. Only one column can serve as the user identifier. Composite identifiers made of two or more columns are not supported.
   Users whose identifier is null, empty, or not found in MoEngage are skipped. Warehouse segments target users MoEngage already knows. Creating a schema does not import new users.
2. Under Map user attributes, configure each column you want to use in segmentation. The heading shows how many columns the table has. For each column, do the following:
   • Display name: Required. Enter the name your marketers see in the segment builder. It defaults to the raw column name, which is rarely what a marketer would search for. Rename usr_ltv_amt to Lifetime Value, dob_dt to Date of Birth, and cust_city_nm to City.
   • Description: Optionally explain what the column holds. The description appears alongside the attribute in the segment builder, which reduces the number of questions that come back to your team.
   • Warehouse data type: The column’s native data type as reported by your warehouse. This is read-only.
   • MoEngage data type: The type MoEngage normalises it to. This is read-only, and it determines which operators are available for the attribute in the segment builder. For the full mapping, refer to Data Types.
   • Click to skip: Select this checkbox to exclude the column. Skipped columns are not read and do not appear in the segment builder.
   To exclude every column at once, select Click to skip all in the header row. To find a specific column in a wide table, use Search by column name. The user identifier cannot be skipped. It is mapped separately above and shows Marked as user identifier in place of its checkbox.
3. To review the columns you excluded, select Show skipped columns. Skipped columns are hidden from the list by default.
4. To map a large table without working through it column by column, click Upload mapping file and supply the mapping as a JSON file. For the file format, refer to Map Columns With a File.
5. Click Create schema. MoEngage runs a validation query against your warehouse to confirm the user identifier column is non-null and unique. On success, MoEngage confirms that the user schema was created and that you can now use warehouse segments to build custom segments.

​

Create an Event Schema

1. On the sidebar menu in MoEngage, click Settings. The Settings page appears.
2. Under Data, click Warehouse Schema. The Warehouse schema page appears.
3. Click + Event schema at the top right. If this is your first event schema for the connection, you can also click Create an event schema in the middle of the page. The Create event schema page appears.
   These options appear only after a user schema exists for the connection. Event schemas are joined to the user schema, so there is nothing to join against until it is created.

​

Step 1: Source and Format

1. Event schema name: Enter a name for the schema. This identifies the schema on the Warehouse schema page and in error messages when a segment fails.
2. Connection: This is pre-filled with the connection you opened the page for.
3. Schema/Dataset: Select the schema or dataset that holds your event table.
4. Table: Select the event table. Tables already used in another schema appear greyed out and cannot be selected. A table can belong to one schema only, whether that is a user schema or an event schema.
5. Columns for preview: Select the columns you want to see in the preview. Use Clear all to reset the selection. Select only the columns you need to recognise the table. Every preview runs a live query against your warehouse, so previewing columns you do not need costs you time and money. Select all is capped at the first 5,000 columns and is not recommended.
6. Click Preview. MoEngage displays the rows returned, up to a maximum of 100.
7. Under Map event, give the table the event name it should be mapped to in MoEngage:
   • Table name: The source table. This is read-only.
   • Event display name: Required. Enter the name your marketers see when they select this event in the segment builder. It defaults to the table name, which is rarely what a marketer would look for. bq_event_order_placed_staging means nothing to them, whereas Order Placed does.
   • Event description: Optionally explain what the event records. The description appears alongside the event in the segment builder.
   One table maps to one event. You cannot map several events from a single table, so select a table whose rows all represent the same event.
8. Click Next. The Mapping step appears.

​

Step 2: Mapping

1. User identifier: Select the column in this table that uniquely identifies each user. This is what MoEngage uses to match rows in your warehouse to users in MoEngage, so the values must correspond to the user identifier in your user schema.
2. Event time: Select the column that records when the event happened. This must be a column that maps to the MoEngage Date-Time type, such as a TIMESTAMP column.
   Event date-times must be stored in UTC. MoEngage converts them to your app timezone when a segment runs. A column stored in local time produces events that appear at the wrong time and fall into the wrong date ranges.
3. Partitioned identifier column: Optional. If your event table is partitioned, select the column it is partitioned on. MoEngage uses it to limit each query to the partitions it needs instead of scanning the whole table, which cuts the cost and time of every segment built on this event. This is often the same column as the event time. A column serving both roles is labelled accordingly in the attribute table below.
4. Under Map event attributes, configure each remaining column. The heading shows how many columns the table has. For each column, do the following:
   • Display name: Required. Enter the name your marketers see in the segment builder.
   • Description: Optionally explain what the column holds.
   • Warehouse data type: The column’s native data type as reported by your warehouse. This is read-only.
   • MoEngage data type: The type MoEngage normalises it to, which determines the operators available in the segment builder. This is read-only. For the full mapping, refer to Data Types.
   • Click to skip: Select this checkbox to exclude the column.
   The user identifier and event time cannot be skipped. They are mapped separately above and show Marked as user identifier and Marked as event time in place of their checkboxes.
5. To map a large table without working through it column by column, click Upload mapping file and supply the mapping as a JSON file. For the file format, refer to Map Columns With a File.
6. Under Test Join, click Test join. MoEngage joins this table to your user master table on the user ID column and returns sample rows. Test join stays disabled until you map the user identifier, because there is nothing to join on until then. If the join returns nothing, MoEngage shows No rows returned and you cannot create the schema until it passes.
   The usual cause is mapping the wrong column as the user identifier. Event tables often carry more than one ID: an order or purchase ID that identifies the row, and a user ID that identifies the person. Only the user ID matches your user master table.
   The join runs against your warehouse, so it can take a few seconds depending on the size of your data.
7. Click Create schema, then click Create to confirm. The button stays disabled until the user identifier and event time are mapped and the test join passes.

​

Map Columns With a File

{
  "mapping": [
    {
      "column_name": "ID",
      "display_name": "Customer ID",
      "description": "The unique identifier assigned by the user to represent a customer",
      "is_skipped": true
    },
    {
      "column_name": "FIRST_NAME",
      "display_name": "First Name",
      "description": "Given name as captured at signup",
      "is_skipped": false
    },
    {
      "column_name": "LAST_NAME",
      "display_name": "Last Name"
    }
  ]
}

• Omit a field to leave its current value untouched. In the LAST_NAME example above, the description keeps whatever it had.
• Set a field to null or "" to clear it. Use this to remove a display name or description you no longer want.

1. On the Mapping step, click Upload mapping file. The Upload mapping file dialog appears.
2. To start from a template rather than writing the file yourself, click Sample file. MoEngage downloads a JSON file you can edit.
3. Drag your file onto the dialog, or click upload from computer and select it. The file must be JSON and smaller than 25 MB.
4. Click Upload.

​

Keep Schemas in Sync

​

Manage Your Schemas

• The user schema for that connection, showing the schema name, source, user identifier, who last updated it, and when.
• Event schemas, showing the schema name, event display name, source table, who last updated it, and when. Use the search box to find a schema by event or schema name, or sort by schema name.

​

View a Schema

​

Edit a Schema

​

Delete a Schema

​

When a Schema Change Breaks a Segment

​

Limits

​

Permissions and Audit Logs

​

Data Types

​

Unsupported Data Types