mixpanel $merge in a nutshell

$merge.md

$merge in 5 mins

Assume 4 unique events (1 → 4) , each with a different distinct_id (A → D)

[{
     "event": 1,
     "properties": {"distinct_id": "A"} 
 },
 {
     "event": 2,
     "properties": {"distinct_id": "B"} 
 },
 {
     "event": 3,
     "properties": {"distinct_id": "C"} 
 },
 {
     "event": 4,
     "properties": {"distinct_id": "D"} 
 }]

Mixpanel recognizes this as unique users, who each did one event:

Now assume that A , B , C, & D are actually different identifiers for the same user

This stream actually represents one user who did four events where 1 → 2 → 3 → 4 is the right "sequence".

For Mixpanel to properly resolve disparate identities together; they need to be $merge-ed

[{
    "event": "$merge",
    "properties": { "$distinct_ids": [ "B", "C" ]}

},
{
    "event": "$merge",
    "properties": { "$distinct_ids": [ "C", "D" ]}

},
{
    "event": "$merge",
    "properties": { "$distinct_ids": [ "A", "C" ]}

}]

when sent (to /import), mixpanel yields:

a few notes:

• $merge is irreversible; you cannot $unmerge

• $merge can be done in any order at any time. the pairs chosen above are arbitrary; as long as A, B, C, & D are connected in with $merge events, mixpanel will resolve the correct sequence

• only 2 uuids can be present in a single $merge event

• any valid distinct_id (alpha string) can $merge

• a user may have no more than 500 unique identifiers

• the canonical distinct_id resulting from any $merge operation is non-deterministic

  • we don't know ahead of time if A or B or C or D will become canonical for the user but all (past and) future events after a merge are resolved properly:

  

  • things get a bit trickier if A, B, C, & D have their own unique user profiles at the time of a $merge ... though this is seldom a problem in 99% of cases.

$merge DOCS