ContactsContract.RawContacts


public static final class ContactsContract.RawContacts
extends Object implements BaseColumns, ContactsContract.ContactNameColumns, ContactsContract.ContactOptionsColumns, ContactsContract.RawContactsColumns, ContactsContract.SyncColumns

java.lang.Object
   ↳ android.provider.ContactsContract.RawContacts


Constants for the raw contacts table, which contains one row of contact information for each person in each synced account. Sync adapters and contact management apps are the primary consumers of this API.

Aggregation

As soon as a raw contact is inserted or whenever its constituent data changes, the provider will check if the raw contact matches other existing raw contacts and if so will aggregate it with those. The aggregation is reflected in the RawContacts table by the change of the ContactsContract.RawContactsColumns.CONTACT_ID field, which is the reference to the aggregate contact.

Changes to the structured name, organization, phone number, email address, or nickname trigger a re-aggregation.

See also AggregationExceptions for a mechanism to control aggregation programmatically.

Operations

Insert

Raw contacts can be inserted incrementally or in a batch. The incremental method is more traditional but less efficient. It should be used only if no Data values are available at the time the raw contact is created:

 ContentValues values = new ContentValues();
 values.put(RawContacts.ACCOUNT_TYPE, accountType);
 values.put(RawContacts.ACCOUNT_NAME, accountName);
 Uri rawContactUri = getContentResolver().insert(RawContacts.CONTENT_URI, values);
 long rawContactId = ContentUris.parseId(rawContactUri);
 

Once Data values become available, insert those. For example, here's how you would insert a name:

 values.clear();
 values.put(Data.RAW_CONTACT_ID, rawContactId);
 values.put(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE);
 values.put(StructuredName.DISPLAY_NAME, "Mike Sullivan");
 getContentResolver().insert(Data.CONTENT_URI, values);
 

The batch method is by far preferred. It inserts the raw contact and its constituent data rows in a single database transaction and causes at most one aggregation pass.

 ArrayList<ContentProviderOperation> ops =
          new ArrayList<ContentProviderOperation>();
 ...
 int rawContactInsertIndex = ops.size();
 ops.add(ContentProviderOperation.newInsert(RawContacts.CONTENT_URI)
          .withValue(RawContacts.ACCOUNT_TYPE, accountType)
          .withValue(RawContacts.ACCOUNT_NAME, accountName)
          .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, "Mike Sullivan")
          .build());

 getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);
 

Note the use of ContentProviderOperation.Builder.withValueBackReference(String, int) to refer to the as-yet-unknown index value of the raw contact inserted in the first operation.

Update

Raw contacts can be updated incrementally or in a batch. Batch mode should be used whenever possible. The procedures and considerations are analogous to those documented above for inserts.

Delete

When a raw contact is deleted, all of its Data rows as well as StatusUpdates, AggregationExceptions, PhoneLookup rows are deleted automatically. When all raw contacts associated with a Contacts row are deleted, the Contacts row itself is also deleted automatically.

The invocation of resolver.delete(...), does not immediately delete a raw contacts row. Instead, it sets the ContactsContract.RawContactsColumns.DELETED flag on the raw contact and removes the raw contact from its aggregate contact. The sync adapter then deletes the raw contact from the server and finalizes phone-side deletion by calling resolver.delete(...) again and passing the ContactsContract.CALLER_IS_SYNCADAPTER query parameter.

Some sync adapters are read-only, meaning that they only sync server-side changes to the phone, but not the reverse. If one of those raw contacts is marked for deletion, it will remain on the phone. However it will be effectively invisible, because it will not be part of any aggregate contact.

Query

It is easy to find all raw contacts in a Contact:

 Cursor c = getContentResolver().query(RawContacts.CONTENT_URI,
          new String[]{RawContacts._ID},
          RawContacts.CONTACT_ID + "=?",
          new String[]{String.valueOf(contactId)}, null);
 

To find raw contacts within a specific account, you can either put the account name and type in the selection or pass them as query parameters. The latter approach is preferable, especially when you can reuse the URI:

 Uri rawContactUri = RawContacts.CONTENT_URI.buildUpon()
          .appendQueryParameter(RawContacts.ACCOUNT_NAME, accountName)
          .appendQueryParameter(RawContacts.ACCOUNT_TYPE, accountType)
          .build();
 Cursor c1 = getContentResolver().query(rawContactUri,
          RawContacts.STARRED + "<>0", null, null, null);
 ...
 Cursor c2 = getContentResolver().query(rawContactUri,
          RawContacts.DELETED + "<>0", null, null, null);
 

The best way to read a raw contact along with all the data associated with it is by using the Entity directory. If the raw contact has data rows, the Entity cursor will contain a row for each data row. If the raw contact has no data rows, the cursor will still contain one row with the raw contact-level information.

 Uri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, rawContactId);
 Uri entityUri = Uri.withAppendedPath(rawContactUri, Entity.CONTENT_DIRECTORY);
 Cursor c = getContentResolver().query(entityUri,
          new String[]{RawContacts.SOURCE_ID, Entity.DATA_ID, Entity.MIMETYPE, Entity.DATA1},
          null, null, null);
 try {
     while (c.moveToNext()) {
         String sourceId = c.getString(0);
         if (!c.isNull(1)) {
             String mimeType = c.getString(2);
             String data = c.getString(3);
             ...
         }
     }
 } finally {
     c.close();
 }
 

Columns

RawContacts
long BaseColumns._ID read-only Row ID. Sync adapters should try to preserve row IDs during updates. In other words, it is much better for a sync adapter to update a raw contact rather than to delete and re-insert it.
long ContactsContract.RawContactsColumns.CONTACT_ID read-only The ID of the row in the ContactsContract.Contacts table that this raw contact belongs to. Raw contacts are linked to contacts by the aggregation process, which can be controlled by the ContactsContract.RawContactsColumns.AGGREGATION_MODE field and AggregationExceptions.
int ContactsContract.RawContactsColumns.AGGREGATION_MODE read/write A mechanism that allows programmatic control of the aggregation process. The allowed values are AGGREGATION_MODE_DEFAULT, AGGREGATION_MODE_DISABLED and AGGREGATION_MODE_SUSPENDED. See also AggregationExceptions.
int ContactsContract.RawContactsColumns.DELETED read/write The "deleted" flag: "0" by default, "1" if the row has been marked for deletion. When ContentResolver.delete(Uri, Bundle) is called on a raw contact, it is marked for deletion and removed from its aggregate contact. The sync adaptor deletes the raw contact on the server and then calls ContactResolver.delete once more, this time passing the ContactsContract.CALLER_IS_SYNCADAPTER query parameter to finalize the data removal.
int ContactsContract.ContactOptionsColumns.STARRED read/write An indicator for favorite contacts: '1' if favorite, '0' otherwise. Changing this field immediately affects the corresponding aggregate contact: if any raw contacts in that aggregate contact are starred, then the contact itself is marked as starred.
String ContactsContract.ContactOptionsColumns.CUSTOM_RINGTONE read/write A custom ringtone associated with a raw contact. Typically this is the URI returned by an activity launched with the RingtoneManager.ACTION_RINGTONE_PICKER intent. To have an effect on the corresponding value of the aggregate contact, this field should be set at the time the raw contact is inserted. To set a custom ringtone on a contact, use the field Contacts.CUSTOM_RINGTONE instead.
int ContactsContract.ContactOptionsColumns.SEND_TO_VOICEMAIL read/write An indicator of whether calls from this raw contact should be forwarded directly to voice mail ('1') or not ('0'). To have an effect on the corresponding value of the aggregate contact, this field should be set at the time the raw contact is inserted.
String ContactsContract.SyncColumns.ACCOUNT_NAME read/write-once The name of the account instance to which this row belongs, which when paired with ContactsContract.SyncColumns.ACCOUNT_TYPE identifies a specific account. For example, this will be the Gmail address if it is a Google account. It should be set at the time the raw contact is inserted and never changed afterwards.
String ContactsContract.SyncColumns.ACCOUNT_TYPE read/write-once

The type of account to which this row belongs, which when paired with ContactsContract.SyncColumns.ACCOUNT_NAME identifies a specific account. It should be set at the time the raw contact is inserted and never changed afterwards.

To ensure uniqueness, new account types should be chosen according to the Java package naming convention. Thus a Google account is of type "com.google".

String ContactsContract.RawContactsColumns.DATA_SET read/write-once

The data set within the account that this row belongs to. This allows multiple sync adapters for the same account type to distinguish between each others' data. The combination of ContactsContract.SyncColumns.ACCOUNT_TYPE, ContactsContract.SyncColumns.ACCOUNT_NAME, and ContactsContract.RawContactsColumns.DATA_SET identifies a set of data that is associated with a single sync adapter.

This is empty by default, and is completely optional. It only needs to be populated if multiple sync adapters are entering distinct data for the same account type and account name.

It should be set at the time the raw contact is inserted and never changed afterwards.

String ContactsContract.SyncColumns.SOURCE_ID read/write String that uniquely identifies this row to its source account. Typically it is set at the time the raw contact is inserted and never changed afterwards. The one notable exception is a new raw contact: it will have an account name and type (and possibly a data set), but no source id. This indicates to the sync adapter that a new contact needs to be created server-side and its ID stored in the corresponding SOURCE_ID field on the phone.
int ContactsContract.SyncColumns.VERSION read-only Version number that is updated whenever this row or its related data changes. This field can be used for optimistic locking of a raw contact.
int ContactsContract.SyncColumns.DIRTY read/write Flag indicating that ContactsContract.SyncColumns.VERSION has changed, and this row needs to be synchronized by its owning account. The value is set to "1" automatically whenever the raw contact changes, unless the URI has the ContactsContract.CALLER_IS_SYNCADAPTER query parameter specified. The sync adapter should always supply this query parameter to prevent unnecessary synchronization: user changes some data on the server, the sync adapter updates the contact on the phone (without the CALLER_IS_SYNCADAPTER flag) flag, which sets the DIRTY flag, which triggers a sync to bring the changes to the server.
String ContactsContract.BaseSyncColumns.SYNC1 read/write Generic column provided for arbitrary use by sync adapters. The content provider stores this information on behalf of the sync adapter but does not interpret it in any way.
String ContactsContract.BaseSyncColumns.SYNC2 read/write Generic column for use by sync adapters.
String ContactsContract.BaseSyncColumns.SYNC3 read/write Generic column for use by sync adapters.
String ContactsContract.BaseSyncColumns.SYNC4 read/write Generic column for use by sync adapters.

Summary

Nested classes

class ContactsContract.RawContacts.Data

A sub-directory of a single raw contact that contains all of its ContactsContract.Data rows. 

class ContactsContract.RawContacts.DisplayPhoto

A sub-directory of a single raw contact that represents its primary display photo. 

class ContactsContract.RawContacts.Entity

A sub-directory of a single raw contact that contains all of its ContactsContract.Data rows. 

Constants

int AGGREGATION_MODE_DEFAULT

Aggregation mode: aggregate immediately after insert or update operation(s) are complete.

int AGGREGATION_MODE_DISABLED

Aggregation mode: never aggregate this raw contact.

int AGGREGATION_MODE_IMMEDIATE

This constant was deprecated in API level 15. Aggregation is synchronous, this historic value is a no-op

int AGGREGATION_MODE_SUSPENDED

Aggregation mode: aggregation suspended temporarily, and is likely to be resumed later.

String CONTENT_ITEM_TYPE

The MIME type of the results when a raw contact ID is appended to CONTENT_URI, yielding a subdirectory of a single person.

String CONTENT_TYPE

The MIME type of the results from CONTENT_URI when a specific ID value is not provided, and multiple raw contacts may be returned.

Inherited constants

String _COUNT

The count of rows in a directory.

String _ID

The unique ID for a row.

String DISPLAY_NAME_ALTERNATIVE

An alternative representation of the display name, such as "family name first" instead of "given name first" for Western names.

String DISPLAY_NAME_PRIMARY

The standard text shown as the contact's display name, based on the best available information for the contact (for example, it might be the email address if the name is not available).

String DISPLAY_NAME_SOURCE

The kind of data that is used as the display name for the contact, such as structured name or email address.

String PHONETIC_NAME

Pronunciation of the full name in the phonetic alphabet specified by PHONETIC_NAME_STYLE.

String PHONETIC_NAME_STYLE

The phonetic alphabet used to represent the PHONETIC_NAME.

String SORT_KEY_ALTERNATIVE

Sort key based on the alternative representation of the full name, DISPLAY_NAME_ALTERNATIVE.

String SORT_KEY_PRIMARY

Sort key that takes into account locale-based traditions for sorting names in address books.

String CUSTOM_RINGTONE

URI for a custom ringtone associated with the contact.

String LAST_TIME_CONTACTED

This constant was deprecated in API level 29. Contacts affinity information is no longer supported as of Android version Build.VERSION_CODES.Q. This column always contains 0.

String PINNED

The position at which the contact is pinned.

String SEND_TO_VOICEMAIL

Whether the contact should always be sent to voicemail.

String STARRED

Is the contact starred?

Type: INTEGER (boolean)

String TIMES_CONTACTED

This constant was deprecated in API level 29. Contacts affinity information is no longer supported as of Android version Build.VERSION_CODES.Q. This column always contains 0.

String ACCOUNT_TYPE_AND_DATA_SET

A concatenation of the account type and data set (delimited by a forward slash) - if the data set is empty, this will be the same as the account type.

String AGGREGATION_MODE

The aggregation mode for this contact.

String BACKUP_ID

Persistent unique id for each raw_contact within its account.

String CONTACT_ID

A reference to the ContactsContract.Contacts._ID that this data belongs to.

String DATA_SET

The data set within the account that this row belongs to.

String DELETED

The "deleted" flag: "0" by default, "1" if the row has been marked for deletion.

String METADATA_DIRTY

This constant was deprecated in API level 30. This column never actually worked since added. It will not supported as of Android version Build.VERSION_CODES.R.

String RAW_CONTACT_IS_READ_ONLY

The "read-only" flag: "0" by default, "1" if the row cannot be modified or deleted except by a sync adapter.

String RAW_CONTACT_IS_USER_PROFILE

Flag that reflects whether this raw contact belongs to the user's personal profile entry.

String ACCOUNT_NAME

The name of the account instance to which this row belongs, which when paired with ACCOUNT_TYPE identifies a specific account.

String ACCOUNT_TYPE

The type of account to which this row belongs, which when paired with ACCOUNT_NAME identifies a specific account.

String DIRTY

Flag indicating that VERSION has changed, and this row needs to be synchronized by its owning account.

String SOURCE_ID

String that uniquely identifies this row to its source account.

String VERSION

Version number that is updated whenever this row or its related data changes.

String SYNC1

Generic column for use by sync adapters.

String SYNC2

Generic column for use by sync adapters.

String SYNC3

Generic column for use by sync adapters.

String SYNC4

Generic column for use by sync adapters.

Fields

public static final Uri CONTENT_URI

The content:// style URI for this table, which requests a directory of raw contact rows matching the selection criteria.

Public methods

static Uri getContactLookupUri(ContentResolver resolver, Uri rawContactUri)

Build a ContactsContract.Contacts.CONTENT_LOOKUP_URI style Uri for the parent ContactsContract.Contacts entry of the given RawContacts entry.

static String getLocalAccountName(Context context)

The default value used for ContactsContract.SyncColumns.ACCOUNT_NAME of raw contacts when they are inserted without a value for this column.

static String getLocalAccountType(Context context)

The default value used for ContactsContract.SyncColumns.ACCOUNT_TYPE of raw contacts when they are inserted without a value for this column.

static EntityIterator newEntityIterator(Cursor cursor)

TODO: javadoc

Inherited methods

Object clone()

Creates and returns a copy of this object.

boolean equals(Object obj)

Indicates whether some other object is "equal to" this one.

void finalize()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

final Class<?> getClass()

Returns the runtime class of this Object.

int hashCode()

Returns a hash code value for the object.

final void notify()

Wakes up a single thread that is waiting on this object's monitor.

final void notifyAll()

Wakes up all threads that are waiting on this object's monitor.

String toString()

Returns a string representation of the object.

final void wait(long timeoutMillis, int nanos)

Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

final void wait(long timeoutMillis)

Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

final void wait()

Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

AGGREGATION_MODE_DEFAULT

Added in API level 5
public static final int AGGREGATION_MODE_DEFAULT

Aggregation mode: aggregate immediately after insert or update operation(s) are complete.

Constant Value: 0 (0x00000000)

AGGREGATION_MODE_DISABLED

Added in API level 5
public static final int AGGREGATION_MODE_DISABLED

Aggregation mode: never aggregate this raw contact. The raw contact will not have a corresponding Contacts aggregate and therefore will not be included in Contacts query results.

For example, this mode can be used for a raw contact that is marked for deletion while waiting for the deletion to occur on the server side.

Constant Value: 3 (0x00000003)

AGGREGATION_MODE_IMMEDIATE

Added in API level 5
Deprecated in API level 15
public static final int AGGREGATION_MODE_IMMEDIATE

This constant was deprecated in API level 15.
Aggregation is synchronous, this historic value is a no-op

Aggregation mode: aggregate at the time the raw contact is inserted/updated.

Constant Value: 1 (0x00000001)

AGGREGATION_MODE_SUSPENDED

Added in API level 5
public static final int AGGREGATION_MODE_SUSPENDED

Aggregation mode: aggregation suspended temporarily, and is likely to be resumed later. Changes to the raw contact will update the associated aggregate contact but will not result in any change in how the contact is aggregated. Similar to AGGREGATION_MODE_DISABLED, but maintains a link to the corresponding Contacts aggregate.

This can be used to postpone aggregation until after a series of updates, for better performance and/or user experience.

Note that changing ContactsContract.RawContactsColumns.AGGREGATION_MODE from AGGREGATION_MODE_SUSPENDED to AGGREGATION_MODE_DEFAULT does not trigger an aggregation pass, but any subsequent change to the raw contact's data will.

Constant Value: 2 (0x00000002)

CONTENT_ITEM_TYPE

Added in API level 5
public static final String CONTENT_ITEM_TYPE

The MIME type of the results when a raw contact ID is appended to CONTENT_URI, yielding a subdirectory of a single person.

Constant Value: "vnd.android.cursor.item/raw_contact"

CONTENT_TYPE

Added in API level 5
public static final String CONTENT_TYPE

The MIME type of the results from CONTENT_URI when a specific ID value is not provided, and multiple raw contacts may be returned.

Constant Value: "vnd.android.cursor.dir/raw_contact"

Fields

CONTENT_URI

Added in API level 5
public static final Uri CONTENT_URI

The content:// style URI for this table, which requests a directory of raw contact rows matching the selection criteria.

Public methods

getContactLookupUri

Added in API level 5
public static Uri getContactLookupUri (ContentResolver resolver, 
                Uri rawContactUri)

Build a ContactsContract.Contacts.CONTENT_LOOKUP_URI style Uri for the parent ContactsContract.Contacts entry of the given RawContacts entry.

Parameters
resolver ContentResolver

rawContactUri Uri

Returns
Uri

getLocalAccountName

Added in API level 30
public static String getLocalAccountName (Context context)

The default value used for ContactsContract.SyncColumns.ACCOUNT_NAME of raw contacts when they are inserted without a value for this column.

This account is used to identify contacts that are only stored locally in the contacts database instead of being associated with an Account managed by an installed application.

When this returns null then getLocalAccountType(Context) will also return null and when it is non-null getLocalAccountType(Context) will also return a non-null value.

Parameters
context Context: This value cannot be null.

Returns
String

getLocalAccountType

Added in API level 30
public static String getLocalAccountType (Context context)

The default value used for ContactsContract.SyncColumns.ACCOUNT_TYPE of raw contacts when they are inserted without a value for this column.

This account is used to identify contacts that are only stored locally in the contacts database instead of being associated with an Account managed by an installed application.

When this returns null then getLocalAccountName(Context) will also return null and when it is non-null getLocalAccountName(Context) will also return a non-null value.

Parameters
context Context: This value cannot be null.

Returns
String

newEntityIterator

Added in API level 8
public static EntityIterator newEntityIterator (Cursor cursor)

TODO: javadoc

Returns
EntityIterator