Definisci i dati utilizzando Entità camera

Quando utilizzi la libreria di persistenza Room per archiviare i dati della tua app, definisci le entità per rappresentare gli oggetti che vuoi archiviare. Ogni entità corrisponde a una tabella nel database Room associato e ogni istanza di un'entità rappresenta una riga di dati nella tabella corrispondente.

L'utilizzo delle entità Room ti consente di definire lo schema del database senza scrivere codice SQL.

Anatomia di un'entità

Definisci ogni entità Room come una classe annotata con @Entity. Un'entità Room include proprietà per ogni colonna della tabella corrispondente nel database, incluse una o più colonne che compongono la chiave primaria.

Il seguente codice è un esempio di un'entità che definisce una tabella User con colonne per ID, nome e cognome:

@Entity
data class User(
    @PrimaryKey val id: Int,
    val firstName: String,
    val lastName: String
)

Per impostazione predefinita, Room utilizza il nome della classe come nome della tabella del database. Se vuoi che la tabella abbia un nome diverso, imposta la tableName proprietà dell' @Entity annotazione. Allo stesso modo, per impostazione predefinita Room utilizza i nomi delle proprietà come nomi delle colonne nel database. Se vuoi che una colonna abbia un nome diverso, aggiungi l' @ColumnInfo alla proprietà e imposta la name. L'esempio seguente mostra i nomi personalizzati per una tabella e le relative colonne:

@Entity(tableName = "users")
data class User(
    @PrimaryKey val id: Int,
    @ColumnInfo(name = "first_name") val firstName: String,
    @ColumnInfo(name = "last_name") val lastName: String
)

Definisci una chiave primaria

Devi definire una chiave primaria per ogni entità Room per identificare in modo univoco ogni riga nella tabella del database corrispondente. Per farlo, annota una singola colonna con @PrimaryKey:

@PrimaryKey val id: Int

Definisci una chiave primaria composta

Se vuoi che le istanze di un'entità siano identificate in modo univoco da una combinazione di più colonne, puoi definire una chiave primaria composta elencando queste colonne nella proprietà primaryKeys di @Entity:

@Entity(primaryKeys = ["firstName", "lastName"])
data class User(
    val firstName: String,
    val lastName: String
)

Ignora proprietà

Per impostazione predefinita, Room crea una colonna per ogni proprietà definita nell'entità. Per impedire a Room di rendere persistente una proprietà, annotala con @Ignore:

@Entity
data class User(
    @PrimaryKey val id: Int,
    val firstName: String,
    val lastName: String,
    @Ignore val picture: Bitmap? = null
)

Se un'entità eredita le proprietà da un'entità principale, utilizza la ignoredColumns proprietà dell'annotazione @Entity:

open class User {
    var picture: Bitmap? = null
}

@Entity(ignoredColumns = ["picture"])
data class RemoteUser(
    @PrimaryKey val id: Int,
    val hasVpn: Boolean
) : User()

Room supporta diverse annotazioni che ti consentono di cercare dettagli nelle tabelle del database.

Supporta la ricerca a testo intero

Se la tua app richiede una ricerca a testo intero (FTS) rapida, esegui il backup delle entità con una tabella virtuale. Utilizza l'estensione SQLite FTS3 o FTS4 o l' estensione SQLite FTS5.

Per utilizzare questa funzionalità, aggiungi l'annotazione @Fts3, @Fts4 o @Fts5 a un'entità.

// Use `@Fts3` only if your app has strict disk space requirements.
@Fts4
@Entity(tableName = "users")
data class User(
    // Specifying a primary key for an FTS-table-backed entity is optional,
    // but if you include one, it must an INTEGER type and column name "rowid".
    @PrimaryKey @ColumnInfo(name = "rowid") val id: Long,
    @ColumnInfo(name = "first_name") val firstName: String
)

Per personalizzare la modalità di tokenizzazione delle informazioni del database nelle tabelle FTS, utilizza l'opzione tokenizer. Room fornisce diversi tokenizer integrati tramite FtsOptions, tra cui TOKENIZER_SIMPLE, TOKENIZER_PORTER e TOKENIZER_UNICODE61:

@Fts4(tokenizer = FtsOptions.TOKENIZER_UNICODE61)
@Entity(tableName = "users")
data class User(
    @PrimaryKey @ColumnInfo(name = "rowid") val id: Long,
    @ColumnInfo(name = "first_name") val firstName: String
)

Room offre diverse altre opzioni per la definizione delle entità di cui è stato eseguito il backup di FTS, tra cui l'ordinamento dei risultati, la rimozione degli indici dalle colonne e le tabelle gestite come contenuti esterni. Per ulteriori informazioni su queste opzioni, consulta il FtsOptions riferimento.

Indicizza colonne specifiche

Se utilizzi AndroidSQLiteDriver e devi supportare le versioni dell'SDK che non supportano le entità di cui è stato eseguito il backup delle tabelle FTS3, FTS4 o FTS5, puoi comunque indicizzare determinate colonne nel database per velocizzare le query. Se utilizzi BundledSQLiteDriver, Room supporta tutte le versioni di FTS indipendentemente dalla versione dell'SDK Android.

Per aggiungere indici a un'entità, includi la indices proprietà nell' @Entity annotazione. Elenca i nomi delle colonne da includere nell'indice o nell'indice composto. Il seguente snippet di codice mostra come aggiungere indici:

@Entity(indices = [Index(value = ["last_name", "address"])])
data class User(
    @PrimaryKey val id: Int,
    @ColumnInfo(name = "first_name") val firstName: String,
    @ColumnInfo(name = "last_name") val lastName: String,
    val address: String?,
)

A volte, alcune colonne o gruppi di colonne in un database devono contenere valori univoci. Per applicare questa unicità, imposta la unique proprietà di un'@Index annotazione su true. Il seguente esempio di codice mostra come applicare questa unicità:

@Entity(indices = [Index(value = ["first_name", "last_name"], unique = true)])
data class User(
    @PrimaryKey val id: Int,
    @ColumnInfo(name = "first_name") val firstName: String,
    @ColumnInfo(name = "last_name") val lastName: String,
)

Avanti
Accedere ai dati utilizzando i DAO