Skip to content

Insert custom data into new or existing contacts

Regular and custom data can only be created/inserted into the database whenever inserting or updating new or existing contacts.

This library provides several insert and update APIs that support custom data integration.

  1. Insert
  2. ProfileInsert
  3. Update

To help illustrate how custom data integrates with these query APIs, we'll use the HandleName and Gender custom data.

ℹ️ For more info, read Integrate the gender custom data and Integrate the handle name custom data.

Creating/inserting custom data into a RawContact

Custom data, just like regular data kinds, are attached to a RawContact. They follow the same rules as regular data kinds.

ℹ️ For more info, read about API Entities.

For example, you are able to add handle names and set gender of a new RawContact,

newRawContact.addHandleName(contactsApi) {
   handle = "dude91"
}
newRawContact.setGender(contactsApi) {
   type = GenderEntity.Type.MALE
}

Once you have created/insert the custom data into the RawContact, you can perform the insert operation on the new RawContact to commit your changes into the database.

For more info, read Insert data into new or existing contacts.

The include function and custom data

All of the above mentioned APIs provide an include function that allows you to include only a given set of fields (data) to be processed in the insert operation. Custom data entries provides fields that can be used in this function.

By default, not calling the include function will include all fields, including custom data fields.

For example, to specifically include only HandleName and Gender fields,

.include(HandleNameFields.all + GenderFields.all)

For more info, read Include only certain fields for read and write operations.

Blank data are not inserted

Blank data are data entities that have only null, empty, or blank primary value(s). Blanks are ignored and are not inserted by insert APIs.

For more info, read about Blank data.