تحديد البيانات باستخدام عناصر الغرفة

عند استخدام مكتبة Room لاستدامة البيانات لتخزين بيانات تطبيقك، عليك تحديد الكيانات التي تمثّل العناصر التي تريد تخزينها. يتوافق كل عنصر مع جدول في قاعدة بيانات Room المرتبطة، ويمثّل كل مثيل لعنصر صفًا من البيانات في الجدول المقابل.

يتيح لك استخدام عناصر Room تحديد مخطط قاعدة البيانات بدون كتابة أي رمز SQL.

بنية الكيان

يمكنك تعريف كل كيان Room كفئة مزوّدة بالتعليق التوضيحي @Entity. يتضمّن العنصر Room سمات لكل عمود في الجدول ذي الصلة في قاعدة البيانات، بما في ذلك عمود واحد أو أكثر يشكّل المفتاح الأساسي.

الرمز التالي هو مثال على كيان يحدد جدولاً يحتوي على أعمدة للمعرّف والاسم الأول واسم العائلة:User

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

يستخدم 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
)

تحديد مفتاح أساسي

يجب تحديد مفتاح أساسي لكل كيان Room من أجل تعريف كل صف في جدول قاعدة البيانات المقابل بشكل فريد. لإجراء ذلك، أضِف تعليقًا توضيحيًا إلى عمود واحد باستخدام @PrimaryKey:

@PrimaryKey val id: Int

تحديد مفتاح أساسي مركّب

إذا كنت بحاجة إلى تعريف مثيلات كيان بشكل فريد من خلال مجموعة من الأعمدة المتعددة، يمكنك تحديد مفتاح أساسي مركّب من خلال إدراج هذه الأعمدة في السمة primaryKeys الخاصة بـ @Entity:

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

تجاهُل المواقع

بشكلٍ تلقائي، ينشئ Room عمودًا لكل سمة محدّدة في العنصر. لمنع Room من الاحتفاظ بقيمة إحدى السمات، أضِف إليها التعليق التوضيحي @Ignore:

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

إذا كان أحد الكيانات يرث سمات من كيان أصلي، استخدِم السمة ignoredColumns الخاصة بالتعليق التوضيحي @Entity:

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

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

تتيح Room العديد من التعليقات التوضيحية التي تتيح لك البحث عن تفاصيل في جداول قاعدة البيانات.

إتاحة البحث في النص الكامل

إذا كان تطبيقك يتطلّب البحث السريع عن النص الكامل (FTS)، يمكنك الاحتفاظ بنسخة احتياطية من عناصرك باستخدام جدول افتراضي. استخدِم إضافة FTS3 أو FTS4 SQLite أو إضافة FTS5 SQLite.

لاستخدام هذه الإمكانية، أضِف التعليق التوضيحي @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
)

لتخصيص طريقة تقسيم معلومات قاعدة البيانات إلى رموز مميّزة في جداول البحث النصي الكامل، استخدِم الخيار 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
)

توفّر Room العديد من الخيارات الأخرى لتحديد الكيانات المتوافقة مع البحث النصي الكامل، بما في ذلك ترتيب النتائج وإزالة الفهارس من الأعمدة والجداول المُدارة كمحتوى خارجي. لمزيد من المعلومات عن هذه الخيارات، يمكنك الاطّلاع على مرجع FtsOptions.

فهرسة أعمدة محدّدة

إذا كنت تستخدم AndroidSQLiteDriver وتحتاج إلى توفير توافق مع إصدارات حزمة تطوير البرامج (SDK) التي لا تتوافق مع الكيانات المستندة إلى جداول FTS3 أو FTS4 أو FTS5، سيظل بإمكانك فهرسة أعمدة معيّنة في قاعدة البيانات لتسريع طلبات البحث. إذا كنت تستخدم BundledSQLiteDriver، يتيح Room جميع إصدارات البحث النصي الكامل (FTS) بغض النظر عن إصدار حزمة تطوير البرامج (SDK) لنظام التشغيل Android.

لإضافة فهارس إلى كيان، أدرِج السمة 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?,
)

في بعض الأحيان، يجب أن تحتوي أعمدة أو مجموعات أعمدة معيّنة في قاعدة بيانات على قيم فريدة. لفرض هذه السمة الفريدة، اضبط السمة 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,
)

التالي
الوصول إلى البيانات باستخدام عمليات DAOs