Menentukan data menggunakan entity Room

Saat menggunakan library persistensi Room untuk menyimpan data aplikasi, Anda menentukan entity untuk merepresentasikan objek yang ingin disimpan. Setiap entity sesuai dengan tabel dalam database Room terkait, dan setiap instance entity mewakili baris data dalam tabel yang sesuai.

Dengan menggunakan entity Room, Anda dapat menentukan skema database tanpa menulis kode SQL apa pun.

Anatomi entity

Anda menentukan setiap entity Room sebagai class yang dianotasikan dengan @Entity. Entitas Room menyertakan properti untuk setiap kolom dalam tabel yang sesuai di database, termasuk satu atau beberapa kolom yang membentuk kunci utama.

Kode berikut adalah contoh entity yang menentukan tabel User dengan kolom untuk ID, nama depan, dan nama belakang:

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

Secara default, Room menggunakan nama class sebagai nama tabel database. Jika Anda ingin tabel memiliki nama yang berbeda, tetapkan properti tableName dari anotasi @Entity. Demikian pula, Room menggunakan nama properti sebagai nama kolom dalam database secara default. Jika Anda ingin kolom memiliki nama yang berbeda, tambahkan anotasi @ColumnInfo ke properti dan tetapkan properti name. Contoh berikut menunjukkan nama-nama kustom untuk tabel dan kolomnya:

@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

Menentukan kunci utama

Anda harus menentukan kunci utama untuk setiap entity Room guna mengidentifikasi setiap baris secara unik dalam tabel database yang sesuai. Untuk melakukannya, anotasikan satu kolom dengan @PrimaryKey:

@PrimaryKey val id: Int
DefiningDataSnippets.kt

Menentukan kunci utama gabungan

Jika memerlukan instance entity untuk diidentifikasi secara unik dengan kombinasi beberapa kolom, Anda dapat menentukan kunci utama gabungan dengan mencantumkan kolom tersebut di properti primaryKeys dari @Entity:

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

Mengabaikan properti

Secara default, Room akan membuat kolom untuk setiap properti yang ditentukan dalam entity. Untuk mencegah Room mempertahankan properti, anotasikan dengan @Ignore:

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

Jika suatu entity mewarisi properti dari parent entity, gunakan properti ignoredColumns dari anotasi @Entity:

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

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

Memberikan dukungan penelusuran pada tabel

Room mendukung beberapa anotasi yang memungkinkan Anda menelusuri detail dalam tabel database.

Mendukung penelusuran teks lengkap

Jika aplikasi Anda memerlukan penelusuran teks lengkap (FTS) yang cepat, dukung entitas Anda dengan tabel virtual. Gunakan ekstensi SQLite FTS3 atau FTS4 atau ekstensi SQLite FTS5.

Untuk menggunakan kemampuan ini, tambahkan anotasi @Fts3, @Fts4, atau @Fts5 ke entity.

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

Untuk menyesuaikan cara informasi database di-tokenisasi dalam tabel FTS, gunakan opsi tokenizer. Room menyediakan beberapa tokenizer bawaan melalui FtsOptions, termasuk TOKENIZER_SIMPLE, TOKENIZER_PORTER, dan 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 menyediakan beberapa opsi lain untuk menentukan entity yang didukung FTS, termasuk pengurutan hasil, menghapus indeks dari kolom, dan tabel yang dikelola sebagai konten eksternal. Untuk mengetahui informasi selengkapnya tentang opsi ini, lihat referensi FtsOptions.

Mengindeks kolom spesifik

Jika Anda menggunakan AndroidSQLiteDriver dan perlu mendukung versi SDK yang tidak mendukung entitas yang didukung oleh tabel FTS3, FTS4, atau FTS5, Anda masih dapat mengindeks kolom tertentu dalam database untuk mempercepat kueri. Jika Anda menggunakan BundledSQLiteDriver, Room mendukung semua versi FTS terlepas dari versi Android SDK.

Untuk menambahkan indeks pada entitas, sertakan properti indices dalam anotasi @Entity. Cantumkan nama kolom yang akan disertakan dalam indeks atau indeks komposit. Cuplikan kode berikut menunjukkan cara menambahkan indeks:

@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

Terkadang, kolom atau grup kolom tertentu dalam database harus berisi nilai unik. Untuk menerapkan keunikan ini, tetapkan properti unique dari anotasi @Index ke true. Contoh kode berikut menunjukkan cara menerapkan keunikan ini:

@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