# Relation

Artifact: [androidx.room:room-common](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/Relation.kt+class:androidx.room.Relation) Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

*** ** * ** ***


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

<br />

*** ** * ** ***

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 `https://developer.android.com/reference/androidx/room/Entity` type is inferred from the return type. If you would like to return a different object, you can specify the `https://developer.android.com/reference/androidx/room/Relation#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 `https://developer.android.com/reference/androidx/room/Entity`, you can use `https://developer.android.com/reference/androidx/room/Relation#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 `https://developer.android.com/reference/androidx/room/Relation#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 `https://developer.android.com/reference/androidx/room/Entity` class cannot have relations. This is a design decision to avoid common pitfalls in `https://developer.android.com/reference/androidx/room/Entity` setups. You can read more about it in the main [Room documentation](https://developer.android.com/training/data-storage/room/referencing-data#understand-no-object-references). When loading data, you can simply work around this limitation by creating POJO classes that extend the `https://developer.android.com/reference/androidx/room/Entity`.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/room/Junction` |   |

## Summary

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room/Junction` | `https://developer.android.com/reference/androidx/room/Relation#getAssociateBy()()` The entity or view to be used as a associative table (also known as a junction table) when fetching the relating entities. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull ?>` | `https://developer.android.com/reference/androidx/room/Relation#getEntity()()` The entity or view to fetch the item from. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/room/Relation#getEntityColumn()()` The column to match in the `https://developer.android.com/reference/androidx/room/Relation#(kotlin.reflect.KClass,kotlin.String,kotlin.String,androidx.room.Junction,kotlin.Array)`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/room/Relation#getParentColumn()()` Reference column in the parent POJO. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull String[]` | `https://developer.android.com/reference/androidx/room/Relation#getProjection()()` If sub columns should be fetched from the entity, you can specify them using this field. |

## 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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room/Junction` | The junction describing the associative table. By default, no junction is specified and none will be used. |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/room/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<@https://developer.android.com/reference/androidx/annotation/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 `https://developer.android.com/reference/androidx/room/Relation#(kotlin.reflect.KClass,kotlin.String,kotlin.String,androidx.room.Junction,kotlin.Array)`.

In a one-to-one or one-to-many relation, this value will be matched against the column defined in `https://developer.android.com/reference/androidx/room/Relation#(kotlin.reflect.KClass,kotlin.String,kotlin.String,androidx.room.Junction,kotlin.Array)`. In a many-to-many using `https://developer.android.com/reference/androidx/room/Relation#(kotlin.reflect.KClass,kotlin.String,kotlin.String,androidx.room.Junction,kotlin.Array)` then this value will be matched against the `https://developer.android.com/reference/androidx/room/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 `https://developer.android.com/reference/androidx/room/Relation#(kotlin.reflect.KClass,kotlin.String,kotlin.String,androidx.room.Junction,kotlin.Array)`. In a many-to-many using `https://developer.android.com/reference/androidx/room/Relation#(kotlin.reflect.KClass,kotlin.String,kotlin.String,androidx.room.Junction,kotlin.Array)` then this value will be matched against the `https://developer.android.com/reference/androidx/room/Junction#parentColumn()`

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html` | 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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull String[]` | The list of columns to be selected from the `https://developer.android.com/reference/androidx/room/Relation#(kotlin.reflect.KClass,kotlin.String,kotlin.String,androidx.room.Junction,kotlin.Array)`. |