The Android people need to update their documentation. It actually served to make me know less about what was happening than I would have gotten from guessing. It suggests that you can pull back a Contact, which will contain many RawContacts which will contain Data.

That interpretation is completely wrong. ContactContracts data is instead three normal average everyday database tables*:

ContactContract Tables

Table: Contacts

Access URI: Contacts.CONTENT_URI

Primary Key**: Data._ID

Description:

This table contains information about a Contact (when was it added, what's is it's user icon, does it have a custom ringtone).

Relationship: It has a 1-to-many relationship with the RawContact table.

Table: RawContacts

Access URI: RawContacts.CONTENT_URI

Primary Key: Data._ID

Foreign Key**: Data.CONTACT_ID

Description:

This table contains information about a related set of Data items. A RawContact could contain Email Type, Email Display Name, Phone Number, Phone Display Name, etc. A RawContact can be aggregated with other RawContacts to make a Contact as a user sees it. A Contact could contain just one RawContact.

Relationship: It has a 1-to-many relationship with the Data table.

Table: Data

Access URI: Data.CONTENT_URI

Primary Key: Data._ID

Foreign Key: Data.RAW_CONTACT_ID

Description:

This table contains a single field of information. An email address, A phone number, A phone number type (home/work), A nickname, A display name.

In answer to the question

I've uploaded the entire sample project to GitHub in order to allow others to see how to query, update and insert records using ContactContract.

You can find the project to download here: https://github.com/gwoodhouse/ContactContractSample

If you just want to look at the java code performing the query/update/insert here is the class file: https://github.com/gwoodhouse/ContactContractSample/blob/master/ContactsIntegration/src/com/woodhouse/example/activity/ContactsIntegrationActivity.java

Hope this helps!

*Not a table, but a ContentProvider

** not strictly true.