Skip to content

Latest commit

 

History

History
91 lines (64 loc) · 3 KB

update-custom-data.md

File metadata and controls

91 lines (64 loc) · 3 KB
Raw

Update custom data

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

  1. Update
  2. ProfileUpdate
  3. DataUpdate

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

ℹ️ For more info about custom data, read Integrate custom data.

Updating custom data via Contacts/RawContacts

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 update existing handle names and the gender of an existing RawContact,

mutableRawContact.handleNames(contactsApi).firstOrNull()?.apply {
   handle = "gal91"
}
mutableRawContact.gender(contactsApi)?.apply {
   type = GenderEntity.Type.FEMALE
}

There are also extensions that allow you to update custom data of an existing RawContact via a Contact, which can be made up of one or more RawContacts,

mutableContact.handleNames(contactsApi).firstOrNull()?.apply {
   handle = "gal91"
}
mutableContact.genders(contactsApi).firstOrNull()?.apply {
   type = GenderEntity.Type.FEMALE
}

Once you have made the updates to existing custom data, you can perform the update operation on the RawContact to commit your changes into the database using Update or ProfileUpdate.

Updating sets of custom data directly

All custom data are compatible with the DataUpdate API, which allows you to update sets of existing regular and custom data kinds.

For example, to update a set of HandleNames and Genders,

val handleNames: List<MutableHandleName>
val genders: List<MutableGender>

val updateResult = Contacts(this)
   .data()
   .update()
   .data(handleNames + genders)
   .commit()

For more info, read Update existing sets of data.

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 update 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 deleted

Blank data are data entities that have only null, empty, or blank primary value(s). Blanks are deleted by update APIs.

For more info, read about Blank data.