Relation

@Target([AnnotationTarget.FIELD, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER]) class Relation
androidx.room.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
  public class Pet {
      @ PrimaryKey
      int id;
      int userId;
      String name;
      // other fields
  }
  public class UserNameAndAllPets {
    public int id;
    public String name;
    @Relation(parentColumn = "id", entityColumn = "userId")
    public List<Pet> pets;
  }
 
  @Dao
  public interface UserPetDao {
      @Query("SELECT id, name from User")
      public List<UserNameAndAllPets> loadUserAndPets();
  }
  

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.

public class User {
      int id;
      // other fields
  }
  public class PetNameAndId {
      int id;
      String name;
  }
  public class UserAllPets {
    @Embedded
    public User user;
    @Relation(parentColumn = "id", entityColumn = "userId", entity = Pet.class)
    public List<PetNameAndId> pets;
  }
  @Dao
  public interface UserPetDao {
      @Query("SELECT * from User")
      public List<UserAllPets> loadUserAndPets();
  }
  

In the example above, PetNameAndId is a regular Pojo but all of fields are fetched from the entity defined in the @Relation annotation (Pet). PetNameAndId 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.

public class UserAndAllPets {
    @Embedded
    public User user;
    @Relation(parentColumn = "id", entityColumn = "userId", entity = Pet.class,
            projection = {"name"})
    public List<String> petNames;
  }
  

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.

Note that the @Relation annotated field cannot be a constructor parameter, it must be public or have a public setter.

Summary

Public constructors

<init>(entity: KClass<Any>, parentColumn: String, entityColumn: String, projection: Array<String>)

A convenience annotation which can be used in a Pojo to automatically fetch relation entities.

Properties

KClass<Any>

The entity or view to fetch the item from.

String

The field path to match in the entity().

String

Reference field in the parent Pojo.

Array<String>

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

Public constructors

<init>

Relation(entity: KClass<Any>, parentColumn: String, entityColumn: String, projection: Array<String>)

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
  public class Pet {
      @ PrimaryKey
      int id;
      int userId;
      String name;
      // other fields
  }
  public class UserNameAndAllPets {
    public int id;
    public String name;
    @Relation(parentColumn = "id", entityColumn = "userId")
    public List<Pet> pets;
  }
 
  @Dao
  public interface UserPetDao {
      @Query("SELECT id, name from User")
      public List<UserNameAndAllPets> loadUserAndPets();
  }
  

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.

public class User {
      int id;
      // other fields
  }
  public class PetNameAndId {
      int id;
      String name;
  }
  public class UserAllPets {
    @Embedded
    public User user;
    @Relation(parentColumn = "id", entityColumn = "userId", entity = Pet.class)
    public List<PetNameAndId> pets;
  }
  @Dao
  public interface UserPetDao {
      @Query("SELECT * from User")
      public List<UserAllPets> loadUserAndPets();
  }
  

In the example above, PetNameAndId is a regular Pojo but all of fields are fetched from the entity defined in the @Relation annotation (Pet). PetNameAndId 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.

public class UserAndAllPets {
    @Embedded
    public User user;
    @Relation(parentColumn = "id", entityColumn = "userId", entity = Pet.class,
            projection = {"name"})
    public List<String> petNames;
  }
  

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.

Note that the @Relation annotated field cannot be a constructor parameter, it must be public or have a public setter.

Properties

entity

val entity: KClass<Any>

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.

Return
KClass<Any>: The entity or view to fetch from. By default, inherited from the return type.

entityColumn

val entityColumn: String

The field path to match in the entity(). This value will be matched against the value defined in parentColumn().

parentColumn

val parentColumn: String

Reference field in the parent Pojo.

If you would like to access to a sub item of a Embeddedd field, you can use the . notation.

For instance, if you have a Embeddedd field named user with a sub field id, you can reference it via user.id.

This value will be matched against the value defined in entityColumn().

Return
String: The field reference in the parent object.

projection

val projection: Array<String>

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

By default, inferred from the the return type.

Return
Array<String>: The list of columns to be selected from the entity().