Skip to main content

Value Extractors

A value extractor is a JSONPath expression that allows you to extract a value from a JSON event.

Syntax​

JSONPath expressions act as queries that enable users to extract specific data from JSON structures. User can leverage a custom value extractor with JSONPath to handle complex data retrieval, simplifying the aggregation and analysis of data within event payloads.

Take a simplified example of an orderPlace event:

{
   "userId": {
      "id": "abc879e",
      "idType": "crm"
   },
   "type": "orderPlace",
   "lineItems": [
      {
         "productId": "sweater11",
         "category": "clothes/winter",
         "categoriesList": ["clothes", "winter"],
         "total": 45.0,
         "currency": "EUR",
         "quantity": 1.0
      },
      {
         "productId": "jeans89",
         "category": "clothes/casual",
         "categoriesList": ["clothes", "casual"],
         "total": 58.0,
         "currency": "EUR",
         "quantity": 1.0
      },
      {
         "productId": "smartphone123",
         "category": "tech/mobile",
         "categoriesList": ["tech", "mobile"],
         "total": 680.0,
         "currency": "EUR",
         "quantity": 2.0,
      }
   ],
   "order": {
      "total": 783,
      "currency": "EUR"
   }
}

The most basic usage of JSONPath is accessing a field. For example, you would write $.order.total to retrieve the total money spent on this order.

Most of the times though you'll want to work with multiple elements at once. $.lineItems gets you the list of line items. You can also apply filtering: $.lineItems[?(@.categoriesList[0] == 'clothes')] returns the same list but only with the products that have a descendant list field named categoriesList whose first element has a value equal to clothes.

For value-based segmentation use cases, you'll likely want to work with aggregations on top of filters, which we implement as extensions to the JSONPath standard:

  • $.lineItems[?(@.categoriesList[0] == 'clothes')].total returns a list of prices of clothes bought, in this case [45.0, 58.0].
  • $..lineItems[?(@.categoriesList[0] == 'clothes')].total.sum() returns the sum of prices of clothes bought, in this case 103.0. Notice the $.. at the start, with the double .., symbolizing aggregation.
  • $..lineItems[?(@.categoriesList[0] == 'clothes')].quantity.sum() returns the number of clothes bought in this order.

We support the following functions on lists: sum, min, max, avg, stddev and length.

Usage in User Attribute Creation​

Intra-event aggregations with JSONPath might be used in different ways to generate the user attribute per se, depending on how you choose to aggregate events. These attributes can then be used to define new segments, such as "customers who spent at least $500 on clothes in the last year" or "customers whose average spend on clothes was at least $50 in the last year." Please refer to the instructions below to build the necessary user attributes for these use cases.

Customers Who Spent at Least $500 on Clothes, in the past Year​

Building the attribute is a 7-step process:

Attribute Creation UI

  1. Filter the event. In this case, select all orderPlace events that have at least one item of the clothes category.
  2. Define the aggregation between different events. In this case, choose Sum to sum the value of the "clothes" category across different orderPlace events for the same user.
  3. Define the event field to extract. Within orderPlace events that contain multiple products of the clothes category, we select the value spent on each different clothes product of the event. Select Custom, and start by writing the path to the relevant field: $.lineItems[?(@.categoriesList[0] == 'clothes')].total.
  4. Define the aggregation between different event fields within the same event. For the list of prices to be summed into a value representing the total spent on all clothes products, use the sum function: $..lineItems[?(@.categoriesList[0] == 'clothes')].total.sum().
  5. Define the default value for users who don't have any clothes purchases in the relevant period. We recommend using 0 for this kind of aggregation.
  6. Choose the period. In this case, the events of the last 365 days.
  7. Define a name and an ID of your attribute, and save it.

We recommend waiting for the processing of historic data to be finished to build the segment. This way, users can leverage insights on segments, like their estimated reach, and fine-tune segment definition.

Segment

Customers Whose Average Spend on Clothes Was at Least $50 in the Last Year​

  1. Filter the event. Please note that, in this example, the way the business defines average is relevant in the decision of the event filter. Consider a user with 3 orders, 2 of which had "clothes" items ($30 and $60), while the third did not.
  • If the target average value is $45 (average clothes spent in orders containing the category), then the event filter (step 1) should specify both the event (orderPlace) and the category.
  • If the target average value is $30 (customer's category spend on each purchase, on average), then the event filter should only specify that the event is an orderPlace.
  1. Define the aggregation between events. In this case, select Average.
  2. Follow the same steps as in the previous example.
Last updated on