Определите данные с помощью объектов комнаты

При использовании библиотеки Room для хранения данных вашего приложения вы определяете сущности, представляющие объекты, которые хотите сохранить. Каждая сущность соответствует таблице в соответствующей базе данных Room, а каждый экземпляр сущности представляет собой строку данных в соответствующей таблице.

Использование сущностей Room позволяет определять схему базы данных без написания какого-либо SQL-кода.

Анатомия сущности

Каждая сущность Room определяется как класс, аннотированный @Entity . Сущность Room включает свойства для каждого столбца в соответствующей таблице базы данных, включая один или несколько столбцов, составляющих первичный ключ .

Приведённый ниже код представляет собой пример сущности, определяющей таблицу User со столбцами для идентификатора, имени и фамилии:

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

По умолчанию Room использует имя класса в качестве имени таблицы базы данных. Если вы хотите, чтобы таблица имела другое имя, установите свойство tableName аннотации @Entity . Аналогично, Room по умолчанию использует имена свойств в качестве имен столбцов в базе данных. Если вы хотите, чтобы столбец имел другое имя, добавьте аннотацию @ColumnInfo к свойству и установите свойство name . В следующем примере показаны пользовательские имена для таблицы и ее столбцов:

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

Определите первичный ключ

Для уникальной идентификации каждой строки в соответствующей таблице базы данных необходимо определить первичный ключ для каждого объекта Room. Для этого добавьте аннотацию @PrimaryKey к отдельному столбцу:

@PrimaryKey val id: Int
DefiningDataSnippets.kt

Определите составной первичный ключ

Если вам необходимо однозначно идентифицировать экземпляры сущности по комбинации нескольких столбцов, вы можете определить составной первичный ключ , перечислив эти столбцы в свойстве primaryKeys аннотации @Entity :

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

Игнорировать свойства

По умолчанию Room создает столбец для каждого свойства, определенного в сущности. Чтобы предотвратить сохранение свойства в Room, добавьте к нему аннотацию @Ignore .

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

Если сущность наследует свойства от родительской сущности, используйте свойство ignoredColumns аннотации @Entity :

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

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

Обеспечить поддержку поиска по таблицам.

Room поддерживает несколько аннотаций, позволяющих осуществлять поиск информации в таблицах базы данных.

Поддерживается полнотекстовый поиск

Если вашему приложению требуется быстрый полнотекстовый поиск (FTS), используйте виртуальную таблицу для поддержки ваших сущностей. Воспользуйтесь расширением SQLite для FTS3 или FTS4, либо расширением SQLite для FTS5 .

Для использования этой возможности добавьте к сущности аннотацию @Fts3 , @Fts4 или @Fts5 .

// 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
)
DefiningDataSnippets.kt

Для настройки способа токенизации информации в таблицах FTS используйте параметр tokenizer . Room предоставляет несколько встроенных токенизаторов через FtsOptions , включая TOKENIZER_SIMPLE , TOKENIZER_PORTER и 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
)
DefiningDataSnippets.kt

Room предоставляет несколько других вариантов определения сущностей, поддерживаемых FTS, включая упорядочивание результатов, удаление индексов из столбцов и управление таблицами как внешним содержимым. Для получения дополнительной информации об этих параметрах см. справочник FtsOptions .

Учитывайте столбцы, специфичные для индекса.

Если вы используете AndroidSQLiteDriver и вам необходимо поддерживать версии SDK, которые не поддерживают сущности на основе таблиц FTS3, FTS4 или FTS5, вы все равно можете индексировать определенные столбцы в базе данных, чтобы ускорить выполнение запросов. Если вы используете BundledSQLiteDriver , Room поддерживает все версии FTS независимо от версии Android SDK.

Чтобы добавить индексы к сущности, включите свойство indices в аннотацию @Entity . Перечислите имена столбцов, которые следует включить в индекс или составной индекс. Следующий фрагмент кода показывает, как добавить индексы:

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

Иногда определенные столбцы или группы столбцов в базе данных должны содержать уникальные значения. Чтобы обеспечить эту уникальность, установите свойство unique аннотации @Index в true . Следующий пример кода показывает, как обеспечить эту уникальность:

@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,
)
DefiningDataSnippets.kt