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.
Good post. Thanks
ReplyDeleteThanks! I had so much confusion before this!
ReplyDeleteWouldn't Robert Langdon's CONTACT_ID be 2?
ReplyDeleteThanks a lot this really clears things up for me :)
ReplyDelete