# Upsert

Artifact: [androidx.room:room-common](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/Upsert.kt+class:androidx.room.Upsert) Added in [2.5.0](https://developer.android.com/jetpack/androidx/releases/room#2.5.0)

*** ** * ** ***


```
@Target(allowedTargets = [AnnotationTarget.FUNCTION])
@Retention(value = AnnotationRetention.BINARY)
public annotation Upsert
```

<br />

*** ** * ** ***

Marks a method in a `https://developer.android.com/reference/androidx/room/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 `https://developer.android.com/reference/androidx/room/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 `https://developer.android.com/reference/androidx/room/Upsert#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)
}
```

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/room/Insert` |   |
| `https://developer.android.com/reference/androidx/room/Update` |   |

## Summary

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull ?>` | `https://developer.android.com/reference/androidx/room/Upsert#getEntity()()` The target entity of the upsert method. |

## Public methods

### getEntity

```
public final @NonNull KClass<@NonNull ?> getEntity()
```

The target entity of the upsert method.

When this is declared, the upsert method parameters are interpreted as partial entities when the type of the parameter differs from the target. The POJO class that represents the entity must contain all of the non-null fields without default values of the target entity.

If the target entity contains a `https://developer.android.com/reference/androidx/room/PrimaryKey` that is auto generated, then the POJO class doesn't need an equal primary key field, otherwise primary keys must also be present in the POJO. If the primary key already exists, only the columns represented by the partial entity fields will be updated

By default the target entity is interpreted by the method parameters.

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull ?>` | the target entity of the upsert method or none if the method should use the parameter type entities. |