Relation

Added in 2.0.0

Kotlin |Java

Cmn

@Target(allowedTargets = [AnnotationTarget.FIELD, AnnotationTarget.FUNCTION])
@Retention(value = AnnotationRetention.BINARY)
annotation Relation

A convenience annotation which can be used in a POJO to automatically fetch relation entities. When the POJO is returned from a query, all of its relations are also fetched by Room.

@Entity
data class Song (
    @PrimaryKey
    val songId: Int,
    val albumId: Int,
    val name: String
    // other fields
)

data class AlbumNameAndAllSongs (
    val id: Int,
    val name: String,
    @Relation(parentColumn = "id", entityColumn = "albumId")
    val songs: List<Song>
)

@Dao
public interface MusicDao {
    @Query("SELECT id, name FROM Album")
    fun loadAlbumAndSongs(): List<AlbumNameAndAllSongs>
}

For a one-to-many or many-to-many relationship, the type of the field annotated with Relation must be a java.util.List or java.util.Set.

By default, the Entity type is inferred from the return type. If you would like to return a different object, you can specify the entity property in the annotation.

data class Album (
    val id: Int
    // other fields
)

data class SongNameAndId (
    val songId: Int,
    val name: String
)

data class AlbumAllSongs (
    @Embedded
    val album: Album,
    @Relation(parentColumn = "id", entityColumn = "albumId", entity = Song.class)
    val songs: List<SongNameAndId>
)

@Dao
public interface MusicDao {
    @Query("SELECT * from Album")
    val loadAlbumAndSongs(): List<AlbumAllSongs>
}

In the example above, SongNameAndId is a regular POJO but all of fields are fetched from the entity defined in the @Relation annotation Song. SongNameAndId could also define its own relations all of which would also be fetched automatically.

If you would like to specify which columns are fetched from the child Entity, you can use projection property in the Relation annotation.

data class AlbumAndAllSongs (
    @Embedded
    val album: Album,
    @Relation(
        parentColumn = "id",
        entityColumn = "albumId",
        entity = Song.class,
        projection = {"name"})
    val songNames: List<String>
)

If the relationship is defined by an associative table (also know as junction table) then you can use associateBy to specify it. This is useful for fetching many-to-many relations.

Note that @Relation annotation can be used only in POJO classes, an Entity class cannot have relations. This is a design decision to avoid common pitfalls in Entity setups. You can read more about it in the main Room documentation. When loading data, you can simply work around this limitation by creating POJO classes that extend the Entity.

See also
`Junction`

Summary

Public constructors
`Relation( entity: KClass<*>, parentColumn: String, entityColumn: String, associateBy: Junction, projection: Array<String> )`	Cmn

Public properties
`Junction`	`associateBy` The entity or view to be used as a associative table (also known as a junction table) when fetching the relating entities.	Cmn
`KClass<*>`	`entity` The entity or view to fetch the item from.	Cmn
`String`	`entityColumn` The column to match in the `entity`.	Cmn
`String`	`parentColumn` Reference column in the parent POJO.	Cmn
`Array<String>`	`projection` If sub columns should be fetched from the entity, you can specify them using this field.	Cmn

Public constructors

Relation

Cmn

Relation(
    entity: KClass<*> = Any::class,
    parentColumn: String,
    entityColumn: String,
    associateBy: Junction = Junction(Any::class),
    projection: Array<String> = []
)

Public properties

associateBy

Cmn

val associateBy: Junction

The entity or view to be used as a associative table (also known as a junction table) when fetching the relating entities.

Returns
`Junction`	The junction describing the associative table. By default, no junction is specified and none will be used.

See also
`Junction`

entity

Cmn

val entity: KClass<*>

The entity or view to fetch the item from. You don't need to set this if the entity or view matches the type argument in the return type.

Returns
`KClass<*>`	The entity or view to fetch from. By default, inherited from the return type.

entityColumn

Cmn

val entityColumn: String

The column to match in the entity.

In a one-to-one or one-to-many relation, this value will be matched against the column defined in parentColumn. In a many-to-many using associateBy then this value will be matched against the Junction.entityColumn.

parentColumn

Cmn

val parentColumn: String

Reference column in the parent POJO.

In a one-to-one or one-to-many relation, this value will be matched against the column defined in entityColumn. In a many-to-many using associateBy then this value will be matched against the Junction.parentColumn

Returns
`String`	The column reference in the parent object.

projection

Cmn

val projection: Array<String>

If sub columns should be fetched from the entity, you can specify them using this field.

By default, inferred from the the return type.

Returns
`Array<String>`	The list of columns to be selected from the `entity`.