Cohort-based Lookalike

Please refer to our user guide documentation to learn more about this feature.

Attributes definition


Attributes selection

A designated cohort is assigned to a user depending of the attributes & features (values of attributes) that you have defined to characterize your users. Once you have selected attributes, you need to format them in a JSON.
We recommend to :
  • Pick attributes that can be used to segment users and that are relevant to the business
  • Pick attributes that are available on all your users (logged / unlogged)
  • Pick attributes from various typology (UserEvent, UserProfile, …)
  • Select between 3 & 10 attributes
  • Have between 50 & 300 features (from all various attributes)
  • Use 10 as Cohort Id Bit Size (corresponds to creating 1024 cohorts)

JSON format

For instance, let's imagine that you want to create cohorts based on:
  • os_family - defined on UserAgentInfo nested in UserAgent
  • age - defined on UserProfile
  • city - defned on UserEvent
You will therefore define the following JSON:
"field_path": "agents.user_agent_info.os_family",
"values": [
"field_path": "profiles.age",
"intervals": [
"from": 0,
"to": 10
"from": 10,
"to": 100
"field_path": "",
"vector_size": 100

Configuration help

There are 3 types of attributes available:
  • FREQUENCY_ENUM: use this type for a finite list of values like operating systems.
  • FREQUENCY_NUMBER: use this type for classifying number buckets like age.
  • FREQUENCY_TEXT: use this type an infinite (or long) liste of values like keywords, cities, ... Choose wisely the vector_size parameter as it will be used as a modulo on values to reduce the disparity of values to a fixed number
The field_path must contain the path of the attribute from the UserPoint definition (see schema documentation for more info)

GraphQL Query

A ML function requires a query to fetch data used in its configuration. In the case of the simhash ML function, it requires the appropriate query to fetch fields used as features and specified in the JSON.
Following our previous example, the graphQL query will be :
{agents {user_agent_info {os_family}} profiles {age} events{city}}

ML function instantiation

Please follow the next steps to instantiate the ML function developed by mediarithmics to assign a cohort to your userpoints:
  1. 1.
    Head to Settings > Datamart > ML Functions
  2. 2.
    Click on New Ml Function, pick the datamart where to apply the ML function then choose simhash-cohorts-calulation
  3. 3.
    Enter the following information on the ML function configuration panel:
    • General Informations
      • Name: Cohort ML Function
      • Hosting Object Type: UserPoint
      • Field Type Name: ClusteringCohort
      • Field Name: clustering_cohort
      • Query: <Insert here the graphQL query that need to be run to extract features used to calculate your cohort>
    • Properties
      • Features: <Insert here the one-line JSON>
      • Cohort Id Bit Size: <Wil be used to define number of cohorts in your datamart as 2^(Cohort Id Bit Size)>
  4. 4.
    Click on Save button

Schema update

Two changes have to be made in your runtime schema :
  • Add a field clustering_cohort in UserPoint as follow :
type UserPoint @TreeIndexRoot(index:"USER_INDEX") {
  • Create a new ClusertingCohort type as follow :
type ClusteringCohort {
id:ID! @TreeIndex(index:"USER_INDEX")
expiration_ts:Timestamp @TreeIndex(index:"USER_INDEX")
cohort_id:String! @TreeIndex(index:"USER_INDEX")
last_modified_ts:Timestamp! @TreeIndex(index:"USER_INDEX")
Don't hesitate to have a look at schema update documentation to learn more about how to update your schema.

ML function


Once the ML function has been instantiated and the run time schema updated, you will need to update batch_mode parameter to true and activate the ML function by running the following API :
"batch_mode": true,
"status": "ACTIVE"

Initial loading

You can ask your Account manager to run an initial loading on your datamart to calculate cohorts on existing userpoints.