Oda varlıklarını kullanarak verileri tanımlama

Uygulamanızın verilerini depolamak için Room kalıcılık kitaplığını kullandığınızda, depolamak istediğiniz nesneleri temsil edecek varlıklar tanımlarsınız. Her varlık, ilişkili Room veri tabanındaki bir tabloya karşılık gelir ve her varlık örneği, ilgili tablodaki bir veri satırını temsil eder.

Room varlıklarını kullanarak SQL kodu yazmadan veritabanı şemanızı tanımlayabilirsiniz.

Bir varlığın anatomisi

Her bir Room öğesini @Entity ile açıklama eklenmiş bir sınıf olarak tanımlarsınız. Bir Room entity, birincil anahtarı oluşturan bir veya daha fazla sütun da dahil olmak üzere veritabanındaki ilgili tablodaki her sütunun özelliklerini içerir.

Aşağıdaki kod, kimlik, ad ve soyadı sütunlarını içeren bir User tablosunu tanımlayan bir varlık örneğidir:

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

Room, varsayılan olarak sınıf adını veritabanı tablosu adı olarak kullanır. Tablonun farklı bir adı olmasını istiyorsanız @Entity açıklamasının tableName özelliğini ayarlayın. Benzer şekilde, Room varsayılan olarak veritabanında sütun adı olarak özellik adlarını kullanır. Bir sütunun farklı bir ada sahip olmasını istiyorsanız özelliğe @ColumnInfo ek açıklamasını ekleyin ve name özelliğini ayarlayın. Aşağıdaki örnekte bir tablo ve sütunları için özel adlar gösterilmektedir:

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

Birincil anahtar tanımlama

İlgili veritabanı tablosundaki her satırı benzersiz şekilde tanımlamak için her bir Room (Oda) öğesi için birincil anahtar tanımlamanız gerekir. Bunu yapmak için @PrimaryKey ile tek bir sütuna açıklama ekleyin:

@PrimaryKey val id: Int

Bileşik bir birincil anahtar tanımlama

Bir öğenin örneklerinin birden fazla sütunun kombinasyonuyla benzersiz şekilde tanımlanması gerekiyorsa bu sütunları @Entity öğesinin primaryKeys özelliğinde listeleyerek bileşik birincil anahtar tanımlayabilirsiniz:

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

Özellikleri yoksay

Varsayılan olarak Room, öğede tanımlanan her özellik için bir sütun oluşturur. Room'un bir özelliği kalıcı hale getirmesini önlemek için özelliği @Ignore ile açıklama ekleyin:

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

Bir varlık, özellikleri ana varlıktan devralıyorsa @Entity ek açıklamasının ignoredColumns özelliğini kullanın:

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

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

Room, veritabanı tablolarınızdaki ayrıntıları aramanıza olanak tanıyan çeşitli ek açıklamaları destekler.

Tam metin arama desteği

Uygulamanızda hızlı tam metin arama (FTS) gerekiyorsa varlıklarınızı sanal bir tabloyla destekleyin. FTS3 veya FTS4 SQLite uzantısını ya da FTS5 SQLite uzantısını kullanın.

Bu özelliği kullanmak için bir öğeye @Fts3, @Fts4 veya @Fts5 notunu ekleyin.

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

Veritabanı bilgilerinin FTS tablolarında nasıl jetonlaştırılacağını özelleştirmek için tokenizer seçeneğini kullanın. Room, FtsOptions aracılığıyla TOKENIZER_SIMPLE, TOKENIZER_PORTER ve TOKENIZER_UNICODE61 dahil olmak üzere çeşitli yerleşik belirteçleyiciler sağlar:

@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, FTS destekli varlıkları tanımlamak için sonuç sıralama, sütunlardan dizinleri kaldırma ve harici içerik olarak yönetilen tablolar gibi başka seçenekler de sunar. Bu seçenekler hakkında daha fazla bilgi için FtsOptions referansına bakın.

Belirli sütunları dizine ekleme

AndroidSQLiteDriver kullanıyorsanız ve FTS3, FTS4 veya FTS5 tablo destekli varlıkları desteklemeyen SDK sürümlerini desteklemeniz gerekiyorsa sorgularınızı hızlandırmak için veritabanındaki belirli sütunları yine de indeksleyebilirsiniz. BundledSQLiteDriver kullanıyorsanız Room, Android SDK sürümünden bağımsız olarak tüm FTS sürümlerini destekler.

Bir varlığa dizin eklemek için indices özelliğini @Entity ek açıklamasına dahil edin. Dizine veya bileşik dizine eklenecek sütun adlarını listeleyin. Aşağıdaki kod snippet'inde dizinlerin nasıl ekleneceği gösterilmektedir:

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

Bazen bir veritabanındaki belirli sütunların veya sütun gruplarının benzersiz değerler içermesi gerekir. Bu benzersizliği zorunlu kılmak için @Index açıklamasının unique özelliğini true olarak ayarlayın. Aşağıdaki kod örneğinde, bu benzersizliğin nasıl zorunlu kılınacağı gösterilmektedir:

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

Sonraki
DAO'ları kullanarak verilere erişme