Android contacts: CONTACT_ID vs RAW_CONTACT_ID - A brief study

2011-04-16T14:49:00.000-07:00

Almost everybody who works with Android contacts asks the same question: What is CONTACT_ID, what is RAW_CONTACT_ID and what is the difference between them? To unveil this mistery for myself, I did some debugging on Android and got a good understanding how it works. Because I couldn't find a comprehensive explanation of this subject anywhere, I decided to share my findings with anybody who would be interested.

In summary, RAW_CONTACT_ID refers to every individual contact you create on Android; this is referred to as raw contact. Some of the raw contacts are automatically grouped together. CONTACT_ID refers to such a group. There is a one-to-many relationship between CONTACT_ID and RAW_CONTACT_ID.

Let's consider some examples and start by creating contact entries.

CREATE A CONTACT

Suppose that we create the following contacts, in the specified order.

1. Katherine Solomon - Home: 01-234-5678

2. Katherine Solomon - Work: katherine.solomon@lostsymbol.com

Android groups these two contacts together and shows them as a single entry in the contacts list. The values of CONTACT_ID and RAW_CONTACT_ID are shown below. We assume that we start from a clean phone; hense the numbers start from 1 (Hint: You can always start from a clean emulator if you wish. Just create a new Android Virtual Device).

Katherine Solomon
1.Data.CONTACT_ID:1
  Data.RAW_CONTACT_ID:1
  StructuredName.DISPLAY_NAME:Katherine Solomon
  StructuredName.GIVEN_NAME:Katherine
  StructuredName.FAMILY_NAME:Solomon
  Phone.NUMBER:01-234-5678
  Phone.TYPE:TYPE_HOME

2.Data.CONTACT_ID:1
  Data.RAW_CONTACT_ID:2
  StructuredName.DISPLAY_NAME:Katherine Solomon
  StructuredName.GIVEN_NAME:Katherine
  StructuredName.FAMILY_NAME:Solomon
  Email.DATA:katherine.solomon@lostsymbol.com
  Email.TYPE:TYPE_WORK

The two "Katherine Solomons" we just created are automatically grouped together and are assigned the same CONTACT_ID. However, each entry has its unique RAW_CONTACT_ID. When you open Android contacts, you'll see one entry for Katherine Solomon, showing both the phone number and the e-mail address. This is the CONTACT. However, when you edit this contact, then you'll see two entries for Katherine Solomon; one showing the phone number and the other showing the e-mail address. These are the RAW_CONTACTS.

Next we add another contact entry:

3. Robert Langdon - Home: 01-876-5432, Work: robert.langdon@lostsymbol.com
(This time we specify both a phone number and an e-mail address when creating the entry.)

Then the related entries for this contact are as follows:

Robert Langdon
  Data.CONTACT_ID:3
  Data.RAW_CONTACT_ID:3
  StructuredName.DISPLAY_NAME:Robert Langdon
  StructuredName.GIVEN_NAME:Robert
  StructuredName.FAMILY_NAME:Langdon
  Phone.NUMBER:01-876-5432
  Phone.TYPE:TYPE_HOME
  Email.DATA:robert.langdon@lostsymbol.com
  Email.TYPE:TYPE_WORK

Because the new contact has a different name, it is not grouped with any of the existing ones and gets its own CONTACT_ID. Android contacts show two entries now, one for Katherine Solomon and one for Robert Langdon.

It's worth to note that there is a 1-to-1 relationship between the CONTACT_ID and the DISPLAY_NAME.

The next question is, what happens when you change the name of a contact. How does this affect, or does it affect the existing groupings?

EDIT THE NAME OF AN EXISTING CONTACT

Suppose that Katherine Solomon gets married and changes her family name to Langdon. Suppose also that we update the family name only of the entry RAW_CONTACT_ID:1 but we do not update the family name of the entry RAW_CONTACT_ID:2.

Then Android contacts still show two entries in the contacts list:

Katherine Solomon
Robert Langdon

Then the related entries for Katherine Solomon are as as displayed below. The arrow (<---) shows the only value which has changed.

Katherine Solomon
1.Data.CONTACT_ID:1
  Data.RAW_CONTACT_ID:1
  StructuredName.DISPLAY_NAME:Katherine Solomon
  StructuredName.GIVEN_NAME:Katherine
  StructuredName.FAMILY_NAME:Langdon <---
  Phone.NUMBER:01-234-5678
  Phone.TYPE:TYPE_HOME

2.Data.CONTACT_ID:1
  Data.RAW_CONTACT_ID:2
  StructuredName.DISPLAY_NAME:Katherine Solomon
  StructuredName.GIVEN_NAME:Katherine
  StructuredName.FAMILY_NAME:Solomon
  Email.DATA:katherine.solomon@lostsymbol.com
  Email.TYPE:TYPE_WORK

Please note that the display name of both entries remain the same and both entries are still grouped together, even though we changed the FAMILY_NAME of one of them.

If we change the FAMILY_NAME of the entry with RAW_CONTACT_ID:2 also, then the display name of the group as well is changed and the following entry appears in Android contacts:

Katherine Langdon
1.Data.CONTACT_ID:1
  Data.RAW_CONTACT_ID:1
  StructuredName.DISPLAY_NAME:Katherine Langdon <---
  StructuredName.GIVEN_NAME:Katherine
  StructuredName.FAMILY_NAME:Langdon
  Phone.NUMBER:01-234-5678
  Phone.TYPE:TYPE_HOME

2.Data.CONTACT_ID:1
  Data.RAW_CONTACT_ID:2
  StructuredName.DISPLAY_NAME:Katherine Langdon <---
  StructuredName.GIVEN_NAME:Katherine
  StructuredName.FAMILY_NAME:Langdon <---
  Email.DATA:katherine.solomon@lostsymbol.com
  Email.TYPE:TYPE_WORK

In my opinion, this behavior is very handy and it makes the life of a software developer very easy when dealing with Android contacts.

But, what is the behavior when we delete contacts?

DELETE A CONTACT

Android contacts allow deleting a CONTACT and not individual RAW_CONTACT. If we delete "Katherine Langdon" then both raw contacts RAW_CONTACT_ID:1 and RAW_CONTACT_ID:2 will be deleted.

Programmatically, it's possible to do more of course.

PROGRAMMATICALLY INSERT A CONTACT INTO A DESIRED GROUP

Suppose that we have the original "Katherine Solomon" contacts we created and we have not deleted any contact entry. Next, we programmatically insert the following contact:

// For brevity the ContactsContract and
// ContactsContract.CommonDataKinds prefixes are ignored.
ArrayList<ContentProviderOperation> ops = new ArrayList<ContentProviderOperation>();
int rawContactInsertIndex = ops.size();
ops.add(ContentProviderOperation.newInsert(RawContacts.CONTENT_URI)
   .withValue(RawContacts.ACCOUNT_TYPE, null)
   .withValue(RawContacts.ACCOUNT_NAME, null)
   .build());
ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI)
   .withValueBackReference(Data.RAW_CONTACT_ID, rawContactInsertIndex)
   .withValue(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE)
   .withValue(StructuredName.DISPLAY_NAME, "Lost Symbol Characters")
   .withValue(StructuredName.GIVEN_NAME, "Katherine")
   .withValue(StructuredName.FAMILY_NAME, "Solomon")
   .build());
ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI)
   .withValueBackReference(Data.RAW_CONTACT_ID, rawContactInsertIndex)
   .withValue(Data.MIMETYPE, Phone.CONTENT_ITEM_TYPE)
   .withValue(Phone.NUMBER, "09876543")
   .withValue(Phone.TYPE, Phone.TYPE_MOBILE)
   .build());
// For brevity, the try-catch statement is ignored.
// Normally it's needed.
getContentResolver().applyBatch(AUTHORITY, ops);

In this operation we specifically assigned a DISPLAY_NAME value to the new contract. Even though the GIVEN_NAME and FAMILY_NAME of the new contact is exactly the same with the contacts RAW_CONTACT_ID:1 and RAW_CONTACT_ID:2, the new contact gets a new CONTACT_ID and appears under a new group. The new entry in Android contacts is as follows:

Lost Symbol Characters
  Data.CONTACT_ID:4
  Data.RAW_CONTACT_ID:4
  StructuredName.DISPLAY_NAME:Lost Symbol Characters
  StructuredName.GIVEN_NAME:Katherine
  StructuredName.FAMILY_NAME:Solomon
  Phone.NUMBER:09876543
  Phone.TYPE:TYPE_MOBILE

PROGRAMMATICALLY DELETE A RAW_CONTRACT

Programmatically it's possible to delete raw contacts. Suppose that we programmaticall delete RAW_CONTACT_ID:1 using the code below.

// For brevity the ContactsContract and
// ContactsContract.CommonDataKinds prefixes are ignored.
ArrayList<ContentProviderOperation> ops = new ArrayList<ContentProviderOperation>();
int rawContactInsertIndex = ops.size();
ops.add(ContentProviderOperation.newDelete(RawContacts.CONTENT_URI)
   .withSelection(RawContacts._ID + " = ?", new String[]{"1"})
   .build());
// For brevity, the try-catch statement is ignored.
// Normally it's needed.
getContentResolver().applyBatch(AUTHORITY, ops);

After this deletion the entries for "Katherine Solomon" are as follows:

Katherine Solomon
  Data.CONTACT_ID:1
  Data.RAW_CONTACT_ID:2
  StructuredName.DISPLAY_NAME:Katherine Solomon
  StructuredName.GIVEN_NAME:Katherine
  StructuredName.FAMILY_NAME:Solomon
  Email.DATA:katherine.solomon@lostsymbol.com
  Email.TYPE:TYPE_WORK

This has been my brief investigation of Android ContactsContract. I also tried to update the DISPLAY_NAME of a raw contract but the behavior I observed seems to be buggy. (The corresponding bug entry is: http://code.google.com/p/android/issues/detail?id=16188&colspec=ID%20Type%20Status%20Owner%20Summary%20Stars) In general my opinion is that, the Android folks did a good job in designing ContactsContract. I find it very convenient to work with it.

Other related blogs:

Email addresses in Android contacts
http://email-addresses-in-android-contacts.blogspot.com/

Geo-Filtered Assistant
http://geo-filtered-assistant.blogspot.com/

Support information sharing:
To support free information sharing please visit one of our sponsors below.