Upsert

Marks a method in a Dao annotated class as an upsert (insert or update) method.

The implementation of the method will insert its parameters into the database if it does not already exists (checked by primary key). If it already exists, it will update its parameters in the database.

All of the parameters of the upsert method must either be classes annotated with Entity or collections/array of it.

Example:

@Dao
interface MusicDao {
  @Upsert
  fun upsertSongs(varargs songs: Song)

  @Upsert
  fun upsertBoth(song1: Song, song2: Song)

  @Upsert
  fun upsertAlbumWithSongs(album: Album, songs: List<Song>)
}

If the target entity is specified via entity then the parameters can be of arbitrary POJO types that will be interpreted as partial entities. For example:

@Entity
data class Playlist (
  @PrimaryKey(autoGenerate = true)
  val playlistId: Long,
  val name: String,
  val description: String?,

  @ColumnInfo(defaultValue = "normal")
  val category: String,

  @ColumnInfo(defaultValue = "CURRENT_TIMESTAMP")
  val createdTime: String,

  @ColumnInfo(defaultValue = "CURRENT_TIMESTAMP")
  val lastModifiedTime: String
)

data class NameAndDescription (
  val name: String,
  val description: String
)

@Dao
interface PlaylistDao {
  @Upsert(entity = Playlist::class)
  fun upsertNewPlaylist(nameDescription: NameAndDescription)
}

Summary

Upsert(entity: KClass<*> = Any::class)

val entity: KClass<*>