# Insert

Artifact: [androidx.room3:room3-common](https://developer.android.com/jetpack/androidx/releases/room3) [View Source](https://cs.android.com/search?q=file:androidx/room3/Insert.kt+class:androidx.room3.Insert) 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 Insert
  ```

*** ** * ** ***

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

The implementation of the function will insert its parameters into the database.

All the parameters of the insert 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 {
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertSongs(varargs songs: Song)

    @Insert
    suspend fun insertBoth(song1: Song, song2: Song)

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

The insert 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. If multiple items are inserted then the return type maybe be of `LongArray` or `List<Array>` containing the ids of the inserted items.

```kotlin
@Dao
interface MusicDao {
    @Insert(onConflict = OnConflictStrategy.IGNORE)
    suspend fun insertSong(song: Song): Long

    @Insert(onConflict = OnConflictStrategy.IGNORE)
    suspend fun insertListOfSongs(List<Song>): List<Long>
}
```

If a target entity is specified via `https://developer.android.com/reference/kotlin/androidx/room3/Insert#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 {
    @Insert(entity = Playlist::class)
    suspend fun insertNewPlaylist(nameDescription: NameAndDescription)
}
```

Note that in the example above the partial entity `NameAndDescription` contains the required properties to fulfill the insert, specifically `name` and `description` while other properties can be left out, such as `category`, `createdTime` and `lastModifiedTime` because they have a `https://developer.android.com/reference/kotlin/androidx/room3/ColumnInfo#defaultValue()` in the target entity. Similarly `playlistId` can be left out because it has `https://developer.android.com/reference/kotlin/androidx/room3/PrimaryKey#autoGenerate()` set to `true`.

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

## Summary

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room3/Insert#Insert(kotlin.reflect.KClass,kotlin.Int)(entity: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<*>, onConflict: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/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/Insert#entity()` The target entity of the insert function. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/room3/Insert#onConflict()` What to do if a conflict happens. | Cmn |

## Public constructors

### Insert

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

```
Insert(
    entity: KClass<*> = Any::class,
    onConflict: Int = OnConflictStrategy.ABORT
)
```

## Public properties

### entity

Cmn

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

The target entity of the insert function.

When this is declared, the insert 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 property, otherwise primary keys must also be present in the data object class.

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 insert function or none if the function should use the parameter type entities. |

### onConflict

Cmn

```
val onConflict: Int
```

What to do if a conflict happens.

Use `https://developer.android.com/reference/kotlin/androidx/room3/OnConflictStrategy#ABORT()` (default) to roll back the transaction on conflict. Use `https://developer.android.com/reference/kotlin/androidx/room3/OnConflictStrategy#REPLACE()` to replace the existing rows with the new rows. Use `https://developer.android.com/reference/kotlin/androidx/room3/OnConflictStrategy#IGNORE()` to keep the existing rows.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | How to handle conflicts. Defaults to `https://developer.android.com/reference/kotlin/androidx/room3/OnConflictStrategy#ABORT()`. |