Bulk upload of model-mapping configurations
With the configuration upload feature, you can quickly edit configuration fields and asset information in Excel and create multiple model-mapping configurations in a single batch
To get started, you can first create 1 model-mapping configuration through the page creation flow, export it, and then copy and modify it in Excel
1. Bulk upload process
Excel configuration upload overview
2. Excel templates
📎 跨源资产映射模板_空白.xlsx（69 KB） 📎 跨源资产映射模板_含样例.xlsx（83 KB）3. Sub-sheets
When you edit model mapping assets configurations in Excel, the following sub-sheets are available
- Model mapping asset configuration list
- Tag table details
- Event property details
- Event name details
- Event and event property relationships
- Entity table details
- Dimension table details
- Enum value configuration
Model mapping assets configuration Excel sub-sheets preview
Each sub-sheet is used as follows
| Sub-sheet name | Type | Usage scenarios |
|---|---|---|
| Model mapping asset configuration list | General | Each row is one model mapping asset configuration and declares information such as the data source, asset type, and configuration fields |
| Tag table details | Tag table | The asset list of the model-mapping tag table, including the original asset name, value acquisition method, output asset name, and so on |
| Event property details | Event Table | The event property asset list of the model-mapping event table, including the original asset name, value acquisition method, output asset name, and so on |
| Event name details | Event Table | The event asset list of the model-mapping event table, including the output event name, original event list, and so on |
| Event and event property relationships | Event Table | The matching relationships between event properties and events in the model-mapping event table |
| Entity table details | Entity table | The asset list of the model-mapping entity table, including the original asset name, value acquisition method, output asset name, and so on |
| Dimension table details | Dimension table | The asset list of the model-mapping dimension table, including the original asset name, value acquisition method, output asset name, and so on |
| Enum value configuration | General | Configures the enum values of tags, event properties, entity properties, and dimension properties |
⚠ In practice, fill in only the sub-sheets you need. For example:
- For a model-mapping tag table, fill in: <Model mapping asset configuration list> and <Tag table details>
- For a model-mapping event table, fill in: <Model mapping asset configuration list>, <Event property details>, <Event name details>, and <Event and event property relationships>
- If some assets need enum values, also fill in <Enum value configuration>
4. Model mapping asset configuration_common fields
| Model mapping asset configuration name | Model mapping asset configuration display name | Description | Asset Type | Data source selection | Table type | Configuration Details | Status |
|---|---|---|---|---|---|---|---|
| route_tag_all_key | ★★Tag table all-fields template★★ | Configuration Details shows all configuration fields and their descriptions ★★★★★★★★★★ | Tag table | hive.ws_test.welletltzi | Wide table | User entities column: efsad_col_1 Entity: User ---Delete this line before uploading--- Tag Name Column: tag_name Tag Value Column: tag_value ---Delete this line before uploading--- Tag Date Version:Only historical version/Only current version/Historical and Current Versions Date column:col_FOULK Date format:yyyyMMdd |
Header fields preview
The fields are described as follows
| Field name | Description |
|---|---|
| Model mapping asset configuration name | The name of the current configuration. It must start with a lowercase letter and can contain digits, lowercase letters, and underscores, up to 80 characters |
| Model mapping asset configuration display name | The display name of the current configuration, up to 80 characters |
| Description | The description of the current configuration, up to 200 characters |
| Asset Type | Can be set to tag table, event table, entity table, or dimension table |
| Data source selection | The data source name. Enter the full name, such as hive.ws_test.tbl_name |
| Table type | Wide table or tall table. Only Tag table assets can be set to tall table |
| Configuration Details | Enter the field configuration in the "name: value" format based on the asset type. For details, see the "Special fields by asset type" section below |
| Status | The validation status of the model-mapping configuration. It's filled in automatically on download; no need to fill it in |
5. Asset list_common fields
After you declare a configuration in the first sub-sheet, set the asset list of that configuration in the asset details sheet of the corresponding type
For example, if the first sub-sheet declares a Model-Mapping Tag Table configuration named route_config_01, a sample tag list to configure in <Tag table details> looks like this
| Model mapping asset configuration name | Original tag name | Original tag type | Output tag name | Output tag display name | Value Acquisition Method | Output tag type | Expansion configuration | Enum Value Logic | Status |
|---|---|---|---|---|---|---|---|---|---|
| route_config_01 | tag_01 | Numeric | tag_01 | Tag_01 | Numeric | Update Mode:Manual Upload | |||
| route_config_01 | tag_02 | Time | tag_02 | Tag_02 | Time | Value Time Zone:8 Description:Time-type tags have the extra "Value Time Zone" field | Update Mode:Manual Upload | ||
| route_config_01 | tag_03 | Text | tag_03 | Tag_03 | Text | Description:Additional description | Update Mode:Manual Upload | ||
| route_config_01 | tag_04 | List | tag_04 | Tag_04 | List | Update Mode:Manual Upload | |||
| route_config_01 | tag_05 | List | tag_05 | Tag_05 | List | Description:Additional description | Update Mode:Manual Upload |
Tag asset list_preview
The header fields differ slightly between asset types. Below, {asset} stands for the asset type
The following fields are required for all asset types. For other special fields and configuration logic, see the "Special fields by asset type" section
| Field Name | Description |
|---|---|
| Model mapping asset configuration name | The name of the model-mapping configuration that the current asset belongs to. It must be filled in <Model mapping asset configuration list> |
| Original {asset} name | Usually the column name in the data source (wide table) or the data row value (tall table) |
| Original {asset} type | Filled in automatically on download; no need to fill it in |
| Output {asset} name | The name of the asset, which must follow the rules for that asset type |
| Output {asset} display name | The display name of the asset, which must follow the rules for that asset type |
| Value acquisition method | To process values specially, enter an SQL function. Once it's filled in, "original asset name" is ignored |
| Output {asset} type | The data type of the asset. If a value acquisition method is used, enter the data type after processing |
| Extended information | Other configuration information of the asset, usually "Description". Other configuration fields may exist in different scenarios |
| Enum Value Logic | Only assets of the Number, String, and List types support enum values. Currently, it can only be set to "Update Mode: Manual Upload" |
| Status | Filled in automatically on download; no need to fill it in |
6. Special fields by asset type
The configuration information of different assets may have cascading dependencies. For details, see the <configuration description> manual of the corresponding asset
The Excel file has the same dependency and validation logic, and adds bulk editing and upload on top of it
6.1 Model-mapping tag table
🔵 Configuration Details
Fill in this information in the "Configuration Details" column of the <Model mapping asset configuration list> sub-sheet
Write multiple fields in the corresponding cell in the "name: value" format, one per line
| Asset Type | Configuration Details |
|---|---|
| Tag table | User entities column: efsad_col_1 Entity: User ---Delete this line before uploading--- Tag Name Column: tag_name Tag Value Column: tag_value ---Delete this line before uploading--- Tag Date Version:Only historical version/Only current version/Historical and Current Versions Date column:col_FOULK Date format:yyyyMMdd |
Model-mapping tag table_configuration details preview
| Field Name | Field category | Requirement | Logic | Sample value |
|---|---|---|---|---|
| Entity column | Entity information | Required | The column in the data source that records the tag entity information | user_name |
| Entity | Entity information | Required | The entity in the project that corresponds to the data source | Player |
| Tag name column | Value information | Only for "tall table" | The column in the tall table that records tag names | tag_name |
| Tag value column | Value information | Only for "tall table" | The column in the tall table that records most tag values | tag_value |
| Tag Date Version | Date version information | Required | Whether the tag data contains date information, and how it's recorded | Only historical version, Only current version, Historical and Current Versions |
| Date column | Date version information | Required when "Tag Date Version" isn't "Only current version" | The column in the data source that records the date information of tag values | tag_date |
| Date format | Date version information | Required when "Tag Date Version" isn't "Only current version" | The format of the date information of tag values in the data source | yyyyMMdd |
🔵 Asset names and data types
Output assets of model-mapping tags support the following data types:
String, Number, Boolean, Time, List
Property names must start with a lowercase letter, contain only lowercase letters, digits, and underscores, and be up to 80 characters long
For complex value acquisition scenarios, see Complex model-mapping configuration scenarios and SQL examples
🔵 Tag expansion configuration
Model-mapping tags need the Value Time Zone field, which marks the time zone of the tag values. The default value is Local time (99)
Some features in the Analytics and Engage suites can only use tags with the same time zone configuration
| Output tag type | Expansion configuration |
|---|---|
| Boolean | Value Time Zone: 99 |
| Numeric | Value Time Zone: 99 |
| Numeric | Description:Additional description Value Time Zone: 99 |
Model-mapping tag_expansion configuration preview
6.2 Model-mapping dimension table
🔵 Configuration Details
Fill in this information in the "Configuration Details" column of the <Model mapping asset configuration list> sub-sheet
Write multiple fields in the corresponding cell in the "name: value" format, one per line
| Asset Type | Configuration Details |
|---|---|
| Dimension table | Entity property type: Event property Entity property: item_id User entities column: item_id ---Delete this line before uploading--- Time format: Hour |
Model-mapping dimension table_configuration details preview
| Field name | Field category | Requirement | Logic | Sample value |
|---|---|---|---|---|
| Entity property type | Entity information | Required | Whether the entity property that needs associated dimension information is an event property or a user property | Event properties |
| Entity property | Entity information | Required | The name of the entity property that needs associated dimension information | item_id |
| Entity column | Entity information | Required | The name of the data column in the data source that's associated with the entity property | item_id |
| Time granularity | Special matching logic | Only when Entity property is of the Time type | If the entity property is of the Time type, the time granularity to truncate to when associating | Month |
⚠ If the data type of the entity property is Time, fill in Time format in the configuration details. The type of the entity column must also be String, with content in the yyyy-MM-dd HH:mm:ss format
Use case: the entity property is "Registration time", the business runs acquisition campaigns in specific months, and the first column of data source A records the campaign month (for example, 2025-01-01). In this case, set the time granularity of the entity property to month as well, and associate it with the first column of data source A
🔵 Asset names and data types
Output assets of model-mapping dimension properties support the following data types:
String, Number, Boolean, Time
Property names must start with a lowercase letter, contain only lowercase letters, digits, and underscores, and be up to 80 characters long
For complex value acquisition scenarios, see Complex model-mapping configuration scenarios and SQL examples
6.3 Model-mapping entity table
In the current version, the model-mapping entity table replaces reported User Properties. To avoid affecting other features, the following information must be configured with ops commands
Data source name, User entities column
Note the following when you configure it in Excel
- A single project can have only 1 Entity table model-mapping configuration
- Model mapping asset configuration name must be the fixed value
user_entity_route - Data source selection must be
hive.ws_product.entity - Configuration Details must be
key: value
🔵 Configuration Details
Fill in this information in the "Configuration Details" column of the <Model mapping asset configuration list> sub-sheet
Write multiple fields in the corresponding cell in the "name: value" format, one per line
| Asset Type | Configuration Details |
|---|---|
| Entity table | User entities column: (configured through ops) keep this placeholder ---Delete this line before uploading--- Data update time column: update_time_pix |
Model-mapping entity table_configuration details preview
| Field name | Field category | Requirement | Logic | Sample value |
|---|---|---|---|---|
| Entity column | Entity information | Required | The column in the data source that records user identification information. It affects user drill-down | user_id |
| Data update time column | Data timeliness information | Optional | The column in the data source that records when the data was updated, used by the Engage suite | update_time |
🔵 Asset names and data types
Output assets of model-mapping dimension properties support the following data types:
String, Number, Boolean, Time, List, Row, Array Row
Property names must start with a lowercase letter, contain only lowercase letters, digits, and underscores, and be up to 80 characters long
For Array Row child properties, separate the parent property name and the child property name with an English period
For complex value acquisition scenarios, see Complex model-mapping configuration scenarios and SQL examples
6.4 Model-mapping event table
🔵 Configuration Details
Fill in this information in the "Configuration Details" column of the <Model mapping asset configuration list> sub-sheet
Write multiple fields in the corresponding cell in the "name: value" format, one per line
| Asset Type | Configuration Details |
|---|---|
| Event Table | User entities column: name of the column that represents the user ID (optional; affects user data drill-down) ---Delete this line before uploading--- Event Name Acquisition Method: Read column value/Constant Event name: fill in when the event name is a constant Event name column: name of the column that contains the event name ---Delete this line before uploading--- Event time value acquisition method: Read column value/custom SQL Event time column: name of the column that contains the event time Event Time Logic: fill in for custom SQL ---Delete this line before uploading--- Event time zone value acquisition method: Read column value/Constant/custom SQL Event Time Zone: fill in when the time zone is a constant Event time zone column: name of the column that contains the event time zone Event time zone logic: fill in for custom SQL ---Delete this line before uploading--- Data partitioning method: Single column date partition/Custom Pushdown Logic Date column: name of the column that contains the date partition Date format: yyyy-MM-dd/yyyymmdd Pushdown Logic: SQL of the custom pushdown logic |
Model-mapping event table_configuration details preview
| Field name | Field category | Requirement | Logic | Sample value |
|---|---|---|---|---|
| Entity column | Entity information | Optional | Name of the column that represents the user ID. It affects user data drill-down | user_id |
| Event name acquisition method | Event name information | Required | Read column value/Constant | Read column value |
| Event name | Event name information | Required when Event Name Acquisition Method = Constant | Fill in when the event name is a constant | user_login |
| Event name column | Event name information | Required when Event Name Acquisition Method = Read column value | Name of the column that contains the event name | event_name |
| Event time acquisition method | Event time information | Required | Read column value/custom SQL | Read column value |
| Event time column | Event time information | Required when Event time value acquisition method = Read column value | Name of the column that contains the event time | event_time |
| Event Time Logic | Event time information | Required when Event time value acquisition method = custom SQL | Fill in for custom SQL | try_cast( ts as timestamp ) |
| Event time zone acquisition method | Event time zone information | Required | Read column value/Constant/custom SQL | Read column value |
| Event Time Zone | Event time zone information | Required when Event time zone value acquisition method = Constant | Fill in when the time zone is a constant | 8 |
| Event time zone column | Event time zone information | Required when Event time zone value acquisition method = Read column value | Name of the column that contains the event time zone | tz |
| Event time zone logic | Event time zone information | Required when Event time zone value acquisition method = custom SQL | Fill in for custom SQL | try_cast( tz as double ) |
| Data partitioning method | Data partition information | Required | Single column date partition/Custom Pushdown Logic | Single column date partition |
| Date column | Data partition information | Required when Data partitioning method = Single column date partition | Name of the column that contains the date partition | pt |
| Date format | Data partition information | Required when Data partitioning method = Single column date partition | yyyy-MM-dd/yyyymmdd | yyyy-MM-dd |
| Pushdown Logic | Data partition information | Required when Data partitioning method = Custom Pushdown Logic | SQL of the custom pushdown logic |
For details about custom pushdown logic, see Complex model-mapping configuration scenarios and SQL examples
🔵 Assets to configure for a model-mapping event table
When you configure a model-mapping event table, set up the following three kinds of assets:
- Event property details
- Event name details
- Event and event property relationships
🔵 Event property names and data types
Output assets of model-mapping event properties support the following data types:
String, Number, Boolean, Time, List, Row, Array Row
Property names must start with a lowercase letter, contain only lowercase letters, digits, and underscores, and be up to 80 characters long
For Array Row child properties, separate the parent property name and the child property name with an English period
For complex value acquisition scenarios, see Complex model-mapping configuration scenarios and SQL examples
🔵 Event name details
| Model mapping asset configuration name | Output event name | Original event list | Output event display name | Expansion configuration | Status |
|---|---|---|---|---|---|
| route_event_config | device_first | Device activation | |||
| route_event_config | login | ('login1', 'login2','login3') | Login | Description: Merges the name changes across 3 versions | |
| route_event_config | level_up | ('lv_u') | Level up |
Event name details preview
Fill in the corresponding model-mapping configuration name in the first column. Fill in the output event name, the original event list, and other information based on your scenario
Event names must start with a lowercase letter, contain only lowercase letters, digits, and underscores, and be up to 60 characters long
Scenario A: Use the values in the event name column directly as output event names
- Enter the original value as the output event name
Scenario B: Merge multiple original events into one output event
- For example, events with the same meaning have multiple original event names because the tracking version changed
- Enter the expected event name in Output event name
- In Original event list, enter the list of original events to merge using English parentheses, single quotes, and commas, such as: ( 'login1', 'login2' )
Scenario C: An original event is renamed
- Same as scenario B: after you enter the output event name, enter 1 event name in the original event list, such as: ( 'login_old' )
🔵 Event and event property relationships
| Model mapping asset configuration name | Event name | Event property name |
|---|---|---|
| route_event_config | device_first | channel |
| route_event_config | login | channel |
| route_event_config | level_up | channel |
| route_event_config | level_up | level_after |
| route_event_config | level_up | map_id |
Event and event property relationships preview
Fill in the corresponding model-mapping configuration name in the first column
In the second and third columns, fill in the associated event name and property name. If an event is associated with multiple properties, fill in multiple rows (such as level_up )