Relation


  • 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

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

Cmn
KClass<*>

The entity or view to fetch the item from.

Cmn
String

The column to match in the entity.

Cmn
String

Reference column in the parent POJO.

Cmn
Array<String>

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

Cmn

Public constructors

Relation

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

Public properties

associateBy

val associateByJunction

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

val entityKClass<*>

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

val entityColumnString

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

val parentColumnString

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

val projectionArray<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.