Relaciones: claves foráneas, @Relation y el problema N+1

Las relaciones son el punto donde el modelo relacional y el modelo de objetos dejan de parecerse. En Kotlin, un autor contiene sus libros; en SQLite, un libro apunta a su autor y nadie contiene a nadie. Room se niega a fingir que esa brecha no existe: separa deliberadamente la integridad, que vive en las claves foráneas, de la composición, que vive en @Relation. Entender que son dos mecanismos independientes, y que el segundo tiene un coste de consultas que conviene conocer, es lo que separa un esquema que aguanta de uno que se degrada con los datos.

Claves foráneas: integridad, no navegación

Una clave foránea declara una regla que el motor debe hacer cumplir: el valor de esta columna tiene que existir en la columna referenciada de otra tabla. Es una restricción de integridad, y no tiene absolutamente nada que ver con poder navegar de un objeto a otro en Kotlin.

@Entity(tableName = "autores")
data class Autor(
    @PrimaryKey(autoGenerate = true) val id: Long = 0L,
    val nombre: String,
)

@Entity(
    tableName = "libros",
    foreignKeys = [
        ForeignKey(
            entity = Autor::class,
            parentColumns = ["id"],
            childColumns = ["autor_id"],
            onDelete = ForeignKey.CASCADE,
        )
    ],
    indices = [Index(value = ["autor_id"])]
)
data class Libro(
    @PrimaryKey(autoGenerate = true) val id: Long = 0L,
    val titulo: String,
    @ColumnInfo(name = "autor_id") val autorId: Long,
)

La política onDelete define qué ocurre al borrar el padre: CASCADE arrastra los hijos, RESTRICT prohíbe el borrado, SET_NULL deja huérfana la referencia si la columna admite nulos, y NO_ACTION difiere la comprobación al final de la transacción. El índice sobre autor_id no es opcional en la práctica: sin él, cada verificación de la restricción y cada consulta por autor recorren la tabla entera, y Room emite un aviso en compilación precisamente por eso.

@Relation: composición sin JOIN

Aquí está el malentendido más extendido del nivel. @Relation no produce un JOIN. Produce una clase contenedora que Room rellena ejecutando consultas separadas y cruzando los resultados en memoria.

data class AutorConLibros(
    @Embedded val autor: Autor,
    @Relation(parentColumn = "id", entityColumn = "autor_id")
    val libros: List<Libro>,
)

@Dao
interface BibliotecaDao {
    @Transaction
    @Query("SELECT * FROM autores ORDER BY nombre")
    suspend fun autoresConLibros(): List<AutorConLibros>
}

@Embedded aplana las columnas del padre dentro del contenedor. @Relation declara la correspondencia entre la columna del padre y la del hijo. Y @Transaction no es decorativo: sin él, las dos consultas que Room ejecuta podrían ver estados distintos de la base si alguien escribe entre medias, produciendo un resultado incoherente. Room avisa en compilación si se te olvida.

Muchos a muchos y el coste real de la comodidad

Una relación muchos a muchos necesita una tabla de unión: una entidad cuyo único cometido es emparejar claves. Room la modela con associateBy y una @Junction.

@Entity(tableName = "libro_etiqueta", primaryKeys = ["libro_id", "etiqueta_id"],
        indices = [Index(value = ["etiqueta_id"])])
data class LibroEtiqueta(
    @ColumnInfo(name = "libro_id") val libroId: Long,
    @ColumnInfo(name = "etiqueta_id") val etiquetaId: Long,
)

data class LibroConEtiquetas(
    @Embedded val libro: Libro,
    @Relation(
        parentColumn = "id",
        entityColumn = "id",
        associateBy = Junction(
            value = LibroEtiqueta::class,
            parentColumn = "libro_id",
            entityColumn = "etiqueta_id",
        )
    )
    val etiquetas: List<Etiqueta>,
)

La clave primaria compuesta impide duplicar el mismo par, y el índice sobre la segunda columna permite recorrer la relación en sentido inverso sin escanear la tabla. Ahora la parte incómoda: al pedir autoresConLibros, Room ejecuta una consulta para los autores y, después, consultas para los libros agrupando identificadores. Room es lo bastante astuto para agrupar en lotes con IN, de modo que el patrón no es literalmente una consulta por autor; pero si el número de padres supera el tamaño de lote se convierte en varias sentencias, y si tú mismo escribes el bucle a mano, el N+1 aparece en su forma canónica.

flowchart TD
A[Necesito autores con sus libros] --> B{Como lo resuelvo}
B -->|Relation| C[Consulta 1: todos los autores]
C --> D[Consulta 2: libros con autor_id IN lote]
D --> E[Room cruza en memoria y arma los objetos]
B -->|JOIN explicito| F[Una sola sentencia con LEFT JOIN]
F --> G[Filas duplicadas del padre que hay que agrupar]
E --> H[Objetos listos, sin duplicar el padre]
G --> H
style E fill:#a6e3a1,color:#11111b
style G fill:#f9e2af,color:#11111b

Cuando la composición se vuelve costosa, la alternativa es un JOIN explícito con un POJO plano y la agrupación en Kotlin, o una consulta agregada si solo necesitas un recuento.

data class AutorConRecuento(
    val id: Long, val nombre: String,
    @ColumnInfo(name = "total_libros") val totalLibros: Int,
)

@Query("""
    SELECT a.id, a.nombre, COUNT(l.id) AS total_libros
    FROM autores a
    LEFT JOIN libros l ON l.autor_id = a.id
    GROUP BY a.id, a.nombre
    ORDER BY total_libros DESC
""")
suspend fun autoresConRecuento(): List<AutorConRecuento>