Relation

@Target(allowedTargets = [AnnotationTarget.FIELD, AnnotationTarget.FUNCTION])
@Retention(value = AnnotationRetention.BINARY)
public 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(
    @NonNull KClass<@NonNull ?> entity,
    @NonNull String parentColumn,
    @NonNull String entityColumn,
    @NonNull Junction associateBy,
    @NonNull String[] projection
)

Public methods

final @NonNull Junction

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

final @NonNull KClass<@NonNull ?>

The entity or view to fetch the item from.

final @NonNull String

The column to match in the entity.

final @NonNull String

Reference column in the parent POJO.

final @NonNull String[]

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

Public constructors

Relation

public Relation(
    @NonNull KClass<@NonNull ?> entity,
    @NonNull String parentColumn,
    @NonNull String entityColumn,
    @NonNull Junction associateBy,
    @NonNull String[] projection
)

Public methods

getAssociateBy

public final @NonNull Junction getAssociateBy()

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

Returns
@NonNull Junction

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

See also
Junction

getEntity

public final @NonNull KClass<@NonNull ?> getEntity()

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
@NonNull KClass<@NonNull ?>

The entity or view to fetch from. By default, inherited from the return type.

getEntityColumn

public final @NonNull String getEntityColumn()

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.

getParentColumn

public final @NonNull String getParentColumn()

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
@NonNull String

The column reference in the parent object.

getProjection

public final @NonNull String[] getProjection()

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
@NonNull String[]

The list of columns to be selected from the entity.