Definiowanie danych za pomocą elementów dotyczących sal

Gdy używasz biblioteki biblioteka trwałości danych Room do przechowywania danych aplikacji, definiujesz encje reprezentujące obiekty, które chcesz zapisać. Każdy element odpowiada tabeli w powiązanej bazie danych Room, a każda instancja elementu reprezentuje wiersz danych w odpowiedniej tabeli.

Używanie elementów Room pozwala zdefiniować schemat bazy danych bez pisania kodu SQL.

Budowa elementu

Każdy element Room definiujesz jako klasę oznaczoną adnotacją @Entity. Element Room zawiera właściwości dla każdej kolumny w odpowiedniej tabeli w bazie danych , w tym co najmniej 1 kolumnę, która tworzy klucz podstawowy.

Poniższy kod to przykład elementu, który definiuje tabelę User z kolumnami na identyfikator, imię i nazwisko:

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

Domyślnie Room używa nazwy klasy jako nazwy tabeli w bazie danych. Jeśli chcesz, aby tabela miała inną nazwę, ustaw właściwość tableName adnotacji @Entity. Podobnie Room domyślnie używa nazw właściwości jako nazw kolumn w bazie danych. Jeśli chcesz, aby kolumna miała inną nazwę, dodaj do właściwości adnotację @ColumnInfo i ustaw właściwość name. Poniższy przykład pokazuje niestandardowe nazwy tabeli i jej kolumn:

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

Definiowanie klucza podstawowego

Musisz zdefiniować klucz podstawowy dla każdego elementu Room, aby jednoznacznie identyfikować każdy wiersz w odpowiedniej tabeli bazy danych. Aby to zrobić, oznacz jedną kolumnę adnotacją @PrimaryKey:

@PrimaryKey val id: Int

Definiowanie złożonego klucza podstawowego

Jeśli chcesz, aby instancje elementu były jednoznacznie identyfikowane przez kombinację kilku kolumn, możesz zdefiniować złożony klucz podstawowy, wymieniając te kolumny we właściwości primaryKeys adnotacji @Entity:

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

Ignorowanie właściwości

Domyślnie Room tworzy kolumnę dla każdej właściwości zdefiniowanej w elemencie. Aby uniemożliwić Room utrwalanie właściwości, oznacz ją adnotacją @Ignore:

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

Jeśli element dziedziczy właściwości z elementu nadrzędnego, użyj ignoredColumns właściwości @Entity adnotacji:

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

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

Room obsługuje kilka adnotacji, które umożliwiają wyszukiwanie szczegółów w tabelach bazy danych.

Obsługa wyszukiwania pełnotekstowego

Jeśli Twoja aplikacja wymaga szybkiego wyszukiwania pełnotekstowego (FTS), utwórz dla swoich elementów tabelę wirtualną. Użyj rozszerzenia SQLite FTS3 lub FTS4 albo rozszerzenia SQLite FTS5.

Aby korzystać z tej funkcji, dodaj do elementu @Fts3, @Fts4 lub @Fts5 adnotację.

// 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
)

Aby dostosować sposób tokenizacji informacji w tabelach FTS, użyj opcji tokenizer. Room udostępnia kilka wbudowanych tokenizatorów za pomocą FtsOptions, w tym TOKENIZER_SIMPLE, TOKENIZER_PORTER, i 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 udostępnia kilka innych opcji definiowania elementów obsługiwanych przez FTS, w tym kolejność wyników, usuwanie indeksów z kolumn i tabele zarządzane jako treści zewnętrzne. Więcej informacji o tych opcjach znajdziesz w dokumentacji FtsOptions.

Indeksowanie określonych kolumn

Jeśli używasz AndroidSQLiteDriver i musisz obsługiwać wersje pakietu SDK , które nie obsługują elementów obsługiwanych przez tabele FTS3, FTS4 ani FTS5, nadal możesz indeksować określone kolumny w bazie danych, aby przyspieszyć wykonywanie zapytań. Jeśli używasz BundledSQLiteDriver, Room obsługuje wszystkie wersje FTS niezależnie od wersji Android SDK.

Aby dodać indeksy do elementu, uwzględnij właściwość indices w adnotacji @Entity. Wymień nazwy kolumn, które mają być uwzględnione w indeksie lub indeksie złożonym. Poniższy fragment kodu pokazuje, jak dodać indeksy:

@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?,
)

Czasami niektóre kolumny lub grupy kolumn w bazie danych muszą zawierać unikalne wartości. Aby wymusić tę unikalność, ustaw właściwość unique adnotacji @Index na true. Poniższy przykładowy kod pokazuje, jak wymusić tę unikalność:

@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,
)

Dalej
Dostęp do danych za pomocą DAO