# Upsert

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

*** ** * ** ***

Common/AllAndroid/JVMNative/C/iOSJavaScript
- Cmn

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

*** ** * ** ***

Marks a function in a `https://developer.android.com/reference/kotlin/androidx/room3/Dao` annotated class as an upsert (insert or update) function.

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

All the parameters of the upsert function must either be classes annotated with `https://developer.android.com/reference/kotlin/androidx/room3/Entity` or collections/array of it.

Example:

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

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

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

The upsert function may have a return type of `Long` if a single item is inserted denoting the `rowid` of the newly inserted item or `-1` if no item was inserted, and instead it was updated. If multiple items are inserted then the return type may be of `LongArray` or `List<Array>` containing the ids of the inserted items.

```kotlin
@Dao
interface MusicDao {
    @Upsert
    suspend fun upsertSong(song: Song): Long

    @Upsert
    suspend fun upsertListOfSongs(List<Song>): List<Long>
}
```

If a target entity is specified via `https://developer.android.com/reference/kotlin/androidx/room3/Upsert#entity()` value then the parameters can be of arbitrary data object types that will be interpreted as partial entities. For example:

```kotlin
@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)
    suspend fun upsertNewPlaylist(nameDescription: NameAndDescription)
}
```

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

## Summary

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room3/Upsert#Upsert(kotlin.reflect.KClass)(entity: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<*>)` | Cmn |

| ### Public properties |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<*>` | `https://developer.android.com/reference/kotlin/androidx/room3/Upsert#entity()` The target entity of the upsert function. | Cmn |

## Public constructors

### Upsert

Cmn Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/room3#3.0.0)

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

## Public properties

### entity

Cmn

```
val entity: KClass<*>
```

The target entity of the upsert function.

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

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

By default, the target entity is interpreted by the function parameters.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<*>` | the target entity of the upsert function or none if the function should use the parameter type entities. |