The Android Developer Challenge is back! Submit your idea before December 2.

Insert

@Target([AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER]) class Insert
androidx.room.Insert

Marks a method in a Dao annotated class as an insert method.

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

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

Example:

@Dao
  public interface MusicDao {
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    public void insertSongs(Song... songs);
 
    @Insert
    public void insertBoth(Song song1, Song song2);
 
    @Insert
    public void insertAlbumWithSongs(Album album, List<Song> songs);
  }
  
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
  public class Playlist {
    @PrimaryKey(autoGenerate = true)
    long playlistId;
    String name;
    @Nullable
    String description
    @ColumnInfo(defaultValue = "normal")
    String category;
    @ColumnInfo(defaultValue = "CURRENT_TIMESTAMP")
    String createdTime;
    @ColumnInfo(defaultValue = "CURRENT_TIMESTAMP")
    String lastModifiedTime;
  }
 
  public class NameAndDescription {
    String name;
    String description
  }
 
  @Dao
  public interface PlaylistDao {
    @Insert(entity = Playlist.class)
    public void insertNewPlaylist(NameAndDescription nameDescription);
  }
  

Summary

Public constructors

<init>(entity: KClass<*>, onConflict: Int)

Marks a method in a Dao annotated class as an insert method.

Properties

KClass<*>

The target entity of the insert method.

Int

What to do if a conflict happens.

Public constructors

<init>

Insert(entity: KClass<*>, onConflict: Int)

Marks a method in a Dao annotated class as an insert method.

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

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

Example:

@Dao
  public interface MusicDao {
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    public void insertSongs(Song... songs);
 
    @Insert
    public void insertBoth(Song song1, Song song2);
 
    @Insert
    public void insertAlbumWithSongs(Album album, List<Song> songs);
  }
  
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
  public class Playlist {
    @PrimaryKey(autoGenerate = true)
    long playlistId;
    String name;
    @Nullable
    String description
    @ColumnInfo(defaultValue = "normal")
    String category;
    @ColumnInfo(defaultValue = "CURRENT_TIMESTAMP")
    String createdTime;
    @ColumnInfo(defaultValue = "CURRENT_TIMESTAMP")
    String lastModifiedTime;
  }
 
  public class NameAndDescription {
    String name;
    String description
  }
 
  @Dao
  public interface PlaylistDao {
    @Insert(entity = Playlist.class)
    public void insertNewPlaylist(NameAndDescription nameDescription);
  }
  

See Also

Properties

entity

val entity: KClass<*>

The target entity of the insert method.

When this is declared, the insert 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 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.

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

Return
KClass<*>: the target entity of the insert method or none if the method should use the parameter type entities.

onConflict

val onConflict: Int

What to do if a conflict happens.

Use OnConflictStrategy#ABORT (default) to roll back the transaction on conflict. Use OnConflictStrategy#REPLACE to replace the existing rows with the new rows. Use OnConflictStrategy#IGNORE to keep the existing rows.

Return
Int: How to handle conflicts. Defaults to OnConflictStrategy#ABORT.