Manage nicknames¶
A nickname is a variation of a customer’s given name that should not affect how customer records are merged together during identity resolution. For example: Mike is a nickname for Michael, Sue and Suzi are nicknames for Susan, Tom and Tommy are nicknames for Thomas, Vicki and Vickie are nicknames for Victoria, and so on.
Stitch uses given names to identify customer records that should (or should not) be grouped together. Nicknames help Stitch associate variations in given names to the sets of records that uniquely identify your customers.
Amperity pre-loads a set of common nicknames to your tenant in the form of a static CSV file. This file has thousands of nicknames, including all of the most common nicknames, along with many variations.
You can upload your files to extend the list of common nicknames to add and/or remove nicknames as needed for your tenant. You can use any file format – CSV, JSON, PSV, TSV, Apache Parquet, etc. – that is supported by Amperity. (This topic uses a CSV file to describe how to manage nicknames.)
About nickname pairs¶
The combination of canonical_name and nickname fields in a nicknames table identifies the pair of names that are used to associate given names with your customers.
For example:
-------- ---------------- ---------- -------------
row_id canonical_name nickname update_type
-------- ---------------- ---------- -------------
1 Michael Mike ADD
2 Victoria Vicki ADD
3 Victoria Vickie ADD
-------- ---------------- ---------- -------------
Whenever you add a nickname, this tells Stitch that each nickname should be associated with the canonical name and that both values can be used to identify the same customer. In this example, “Mike” is added as a nickname for “Michael”, while “Vicki” and “Vickie” are added as nicknames for “Victoria”.
The following table tells Stitch which nicknames should not be associated with the canonical name and should not be used to identify the same customer. In this example, “Sally” and “Shelly” should not be nicknames for “Susan”, while “Tim” and “Timmy” should not be nicknames for “Thomas”.
-------- ---------------- ---------- -------------
row_id canonical_name nickname update_type
-------- ---------------- ---------- -------------
1 Susan Sally REMOVE
2 Susan Shelly REMOVE
3 Thomas Tim REMOVE
4 Thomas Timmy REMOVE
-------- ---------------- ---------- -------------
Note
Add and remove requests can be combined into the same file:
-------- ---------------- ---------- -------------
row_id canonical_name nickname update_type
-------- ---------------- ---------- -------------
1 Michael Mike ADD
2 Susan Sally REMOVE
3 Victoria Vicki ADD
4 Susan Shelly REMOVE
5 Thomas Tim REMOVE
6 Victoria Vickie ADD
7 Thomas Timmy REMOVE
8 Daniel Danny REMOVE
-------- ---------------- ---------- -------------
If you add a nickname for a canonical name that does not exist, a new row is added. For example, if “Daniel” does not exist in your nicknames list, row 8 will add “Daniel” and add a nickname for “Danny”.
If a nickname is added and removed, Amperity will ignore the remove request and keep the nickname in the list.
Upload CSV file¶
You may upload a file to Amperity that contains a list of nicknames that should be added to or removed from the nicknames file. For example, a CSV file would be similar to:
row_id,canonical_name,nickname,update_type
1,Michael,Mike,ADD
2,Victoria,Vickie,ADD
3,Thomas,Tim,REMOVE
Add this file to your tenant using a manual upload and a feed named “Nicknames”. Name the source after the file type you are using. For example: “CSV”.
Apply the following semantic tags:
nicknames/canonical-name to canonical_name
nicknames/nickname to nickname
nicknames/update-type to update_type
and then activate the feed.
Examples¶
The following examples show how you can use a nicknames table to manage the list of nicknames that are associated with the customers in your database.
Important
Nicknames are a part of how Stitch evaluates records to determine if they match. The presence of nicknames is not enough to ensure that records will match. Records that have given names that are nicknames, but are otherwise very different, are unlikely to match.
Note
This topic uses similar examples as the ones in the Stitch labels topic to show how to use nicknames instead of Stitch labels to help Stitch evaluate records so they are grouped correctly.
If the match/mismatch is due to issues unrelated to given names, you should consider using Stitch labels instead of nicknames to resolve the issue.
Name conflicts¶
Teaninau and Teeyon are phonetically similar names, but are not obvious nicknames and after examining the merged customer records it may be unclear that these individuals should be part of the same customer record. They may be related, as there are some shared details.
If the customer records are merged, and you believe they should not be part of the same customer record, add an entry to your nicknames table:
row_id,canonical_name,nickname,update_type
1,Teaninau,Teeyon,REMOVE
and then upload it to Amperity. Verify the results to see if Teaninau and Teeyon are split into individual groupings.
If the customer records are split, and you believe they should be part of the same customer record, add an entry to your nicknames table:
row_id,canonical_name,nickname,update_type
1,Teaninau,Teeyon,ADD
and then upload it to Amperity. Verify the results to see if Teaninau and Teeyon are merged into the same grouping.
Gender mismatch from typo¶
Adam and Ada are not the same name and it is unlikely that Ada is a nickname for Adam.
Add an entry to the nicknames table to decrease the likelihood that Stitch will consider two records as having the same given name:
row_id,canonical_name,nickname,update_type
1,Adam,Ada,REMOVE
Likely nickname¶
Ty and Tylian were split into two customer records, but after examining the split customer records and noticing they share other details (email address and phone number), it’s very likely that Ty is a nickname for Tylian.
Add an entry to the nicknames table to increase the likelihood that Ty and Tylian are considered matching given names:
row_id,canonical_name,nickname,update_type
1,Tylian,Ty,ADD