Updatable events

Last updated 10/03/2026

This section describes how to use updatable events, a special data structure in the AE system. An updatable event is a type of special event data whose event property values can be updated. It is suitable for recording event data that contains changing status values or changing cumulative values. For example, for a cost event, the cost (cost amount) property can be updated over time.

warning

Storing and processing updatable events incurs significant performance overhead. To ensure data processing efficiency and query performance, they are suitable only for events with a small volume and strong update needs in special business scenarios. We strongly recommend that you use them with the assistance of ThinkingAI staff

1. Data structure

If you use an AE client SDK or server SDK, see the integration guide of that SDK. The "Updatable events" and "Overwritable events" sections of the guide describe in detail how to call the APIs

To use updatable events, make two adjustments to your data:

1. Set the #type field, which identifies the data type, to track_update or track_overwrite. These two data types represent two ways of updating events: updating some properties and overwriting all properties
2. Add the #event_id field, which is the unique identifier of the event. When properties are updated, the corresponding event data is looked up by #event_name and #event_id, and that record is updated. The #event_id values of different events are independent of each other, so each updatable event has its own unique identifier system

The following is a sample record. Note where #event_id is located:

{
  "#account_id": "ABCDEFG-123-abc",
  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
  "#type": "track_update",
  "#event_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
  "#time": "2020-08-18 14:37:28.527",
  "#event_name": "test_event",
  "properties": {
    "argString": "abc"
  }
}

2. Data processing logic

Updatable events are processed very differently from regular event data: Note that if an event record's #type is track, the record cannot be updated later. If an event record's #type is track_update or track_overwrite, it is treated as an updatable event, and its properties can later be updated with either type of data.

The AE system processes track_update and track_overwrite data differently. This section describes the processing logic of these two data types in detail.

2.1 Processing logic of track_update

When #type in the data is track_update, the data is processed as an event property update. When the system receives this type of data, it checks whether the corresponding event data exists based on the #event_id field. If it exists, the corresponding fields are updated. The processing logic is as follows:

1. If no data corresponding to the #event_id exists under the event, the data is treated as new data and stored directly
2. If the #event_id exists, the event properties in the new data update the previous values, and any new properties are added. Properties not included in the new data are not updated, so you only need to pass the properties to be updated
3. In addition, #time (Event Time) is also updated by the new data, so set the time in the new data appropriately for your business scenario

2.2 Processing logic of track_overwrite

When #type in the data is track_overwrite, the data is processed as an event overwrite. When the system receives this type of data, it checks whether the corresponding event data exists based on the #event_id field. If it exists, that record is deleted and the new event data is written to the system (which is equivalent to replacing the deleted record). The processing logic is as follows:

1. If no data corresponding to the #event_id exists under the event, the data is treated as new data and stored directly
2. If the #event_id exists, all content of the event record is overwritten. To update only some properties, use track_update
3. In addition, #time (Event Time) is also updated by the new data, so set the time in the new data appropriately for your business scenario

3. Best practices

Ad cost

In ad performance analysis, you often need to calculate the ROI (return on investment) of ad placements or creatives, that is, the ratio of user value to user cost. User value, the sum of direct payments and value generated in other ways, is easy to record. Cost data, however, depends on the data rules of the ad platform, and the cost amount is usually updated continuously, so it is not suitable for recording as regular event data.

Because cost data keeps changing, ad cost data is well suited to being recorded as updatable data. When you record ad cost data for the first time, you can upload the following data:

{
  "#account_id": "admin",
  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
  "#type": "track_update",
  "#event_id": "2020-09-01_google_7-Tier1-0527_adset1_adname1",
  "#time": "2020-09-01 00:00:00.000",
  "#event_name": "ad_cost",
  "properties": {
    "channel": "google",
    "campaignid": "7-Tier1-0527",
    "adset": "adset1",
    "adname": "adname1",
    "cost": 100
  }
}

The data above adds an updatable cost event. #event_id is a concatenation of the date, channel, campaign name, ad set, and ad name, and serves as the unique ID of the cost. In terms of data logic, this is also the finest granularity at which the cost event can be updated. The cost field records the current ad cost of 100 yuan.

Over time, the ad channel pushes new cost data, and the new ad cost is 200. You can then send the following data. #event_id must be the same as in the previous data, which indicates that the previous record is updated. The cost field is updated with the new cost value of 200. Because #time is also updated by the new data, it must be the same as before; pass the cost date (converted to the time type). Other fields, such as the channel, campaign, and ad placement, do not need to be updated, so you can omit them from the data.

{
  "#account_id": "admin",
  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
  "#type": "track_update",
  "#event_id": "2020-09-01_google_7-Tier1-0527_adset1_adname1",
  "#time": "2020-09-01 00:00:00.000",
  "#event_name": "ad_cost",
  "properties": {
    "cost": 200
  }
}

When the system receives this event, it checks whether the #event_id already exists. After finding it, the system updates the #time and cost fields in the original data (the first sample record), which completes the update of the cost amount of the cost event.