Using Calculated Attributes

Create, activate, and use calculated attributes from the mParticle user interface or Platform API. You can then view calculated attributes along with other user attributes in the UI or via the Profile API.

Step one: create a calculated attribute

1. Within the Data Master section of your dashboard’s side navigation panel, select Calculated Attributes, and then select + Calculated Attribute.
2. Enter the Calculated Attribute Name and an optional Description.
3. Select the Category of calculation. See Calculation Categories for details.
4. Click Next to display the criteria section.

5. Define the data used to run the calculation.

   a. Select values from the drop-downs to define and add criteria as needed.

   • For Value Based Pricing customers, only events set to Personalize can be used as criteria in a calculated attribute. Events set to other tiers are grayed out.
   • Some operations require a specific data type to run a calculation. When a selected attribute is incompatible with the operation, a warning message is displayed. If you want to force the use of a specific event attribute, you can continue past the warning and activate the calculated attribute. For example, if you pass in the purchase amount as a string, you can force it to be a number for use in a sum calculation.

   b. Click Next to select a date range.

6. To choose the date range for your calculation, click on the Date Range drop-down:

   • Select Since from the dropdown for calculations that must be made from a specific start date within the audience retention period defined in your subscription plan.
   • Select Within the last for calculations that must be made over a specific rolling time period. Enter a number and specify a time unit of Days or Weeks

   • Select All Time to use all the data available per your long-term data retention policy. Therefore, selecting All Time may incur additional expenses due to larger data volumes.

7. You can seed the calculated attribute with historical data if you select Since or All Time for your date range. To seed, add the date you want to start using incoming mParticle data—it can be a date different from the last date of seeded data. If you don’t want to seed this calculated attribute, click the X on the right to remove it. For more information about seeding, see Seed a calculated attribute.

   

8. Save your changes.

Step two: activate a calculated attribute

A calculated attribute must be activated before mParticle starts calculating its values across your users.

To activate a calculated attribute:

1. If it’s not already open, go to Data Master > Calculated Attributes and click the calculated attribute to open it.
2. Select Activate.
3. Once activated, the calculated attribute is immediately available across the mParticle platform. You can then create audiences or set up connections and data filters.

When activated, mParticle computes and initializes the value for the calculated attribute.

Depending on the date range, volume of data in your workspace, and definition complexity, calculations require different amounts of time before they are available across your customer profiles. While calculating, the UI displays progress of the initialization.

Optional step: using the Calculated Attributes feed

You can use the default behavior for forwarding calculated attributes forwarding, or you can use the special Calculated Attributes feed.

Forward calculated attributes in event batches (default behavior)

mParticle automatically enriches incoming batches with active calculated attributes for that user. Like regular user attributes, you can restrict which outputs receive them using data filters.

Forward calculated attributes in the Calculated Attributes Feed

The Calculated Attributes feed allows you to send calculated attributes downstream whenever they change, without an event from the user. This feed is especially useful for keeping calculated attributes with asynchronous calculations synchronized throughout your stack, and for sending calculated attributes downstream alongside kit integrations.

If your output partner supports the Calculated Attributes Feed, the input appears once you have activated a calculated attribute. When a new connection is made to this input, calculated attribute values for users who have not been seen since their asynchronous calculated attributes were calculated are sent. This feed sends an update when calculated attributes change (both synchronous & asynchronous); it does not send user attributes.

To control which downstream system receives these updates, connect specific platforms to receive the calculated attribute updates. You can also filter out calculated attributes you do not wish to forward using the platform filters page.

The calculated attributes feed is available with the following partners:

• Amazon Kinesis
• Amazon Kinesis Firehose
• Amazon Redshift
• Amazon S3
• Amazon SNS
• Amplitude
• Apache Kafka
• Braze
• Google BigQuery
• Google Cloud Storage
• Google Pub/Sub
• Microsoft Azure Blob Storage
• Microsoft Azure Event Hubs
• Slack
• Snowflake
• Webhook

View calculated attributes in Live Stream, User Activity view, or Profile API

Calculated attributes can be viewed alongside other user attributes in the Live Stream and the User Activity view, and are accessible via the Profile API.

Use calculated attributes in audiences

Use calculated attributes in the Audience builder by selecting User > Calculated Attributes.

Calculated attributes appear as ‘string’ types at first and then automatically switch to the correct type as they are computed across many users. You can build audience criteria with a calculated attribute even if it is calculating. After the attribute values are completed for each user, their audience membership is updated.

Seed a calculated attribute

Seeding allows you to pass in historical values for calculated attributes that mParticle will build upon as new data arrives without passing in all the raw events. Seeding allows you to seamlessly transition from your own calculations to mParticle’s.

To use seeds with a calculated attribute:

1. Define a calculated attribute in the mParticle platform before sending any seeds.

   The calculated attribute can be in either draft or active state. However, mParticle recommends the calculated attribute be activated after seeds for all users have been sent to mParticle. Once a calculated attribute is activated, mParticle starts calculating it, and thus some users may show inaccurate values until all seeds have been received.

2. Send seeds via the Calculated Attributes Seeding API.

   Calculated attribute creation or update takes up to five minutes to be included in the mParticle cache. Therefore, if you send seeds immediately after creating or updating a calculated attribute, mParticle may send a NOT FOUND error.

Once mParticle has received seeds, mParticle combines them with calculated attribute results based on live data received after the cutoff date.

Calculated attribute changes and seeding

After seeds have been sent to mParticle, any of the following changes make the previously received seeds invalid and are deleted from mParticle.

• Calculated attribute name
• Calculated attribute calculation type, such as from sum to count
• Seeding cutoff date
• Deleting the calculated attribute

Updating seeds

To update the seeds after you have sent them to mParticle, send the updated seeds to mParticle again. mParticle overwrites previously received seeds.

Historical data loads require recalculation

If you load historical data using the historical endpoint of the HTTP API, after loading, you must recreate new calculated attributes or update the definition of an existing CA to trigger a recalculation.