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

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

وهذا يعني أنّه يمكنك استخدام كيانات الغرف لتحديد قاعدة بياناتك. بدون مخطط وكتابة أي تعليمة SQL.

بنية الكيان

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

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

Kotlin

@Entity
data class User(
    @PrimaryKey val id: Int,

    val firstName: String?,
    val lastName: String?
)

Java

@Entity
public class User {
    @PrimaryKey
    public int id;

    public String firstName;
    public String lastName;
}

ملاحظة: للاحتفاظ بحقل، يجب أن تكون لدى الغرفة إذن الوصول إليه. يمكنك التأكد من أنّ الغرفة حق الوصول إلى حقل إما بجعله عامًا أو من خلال تقديم لتحديد تلك الطرق.

تستخدم الغرفة تلقائيًا اسم الفئة كاسم لجدول قاعدة البيانات. إذا كنت ترغب في الجدول له اسم مختلف، اضبط السمة tableName تعليق توضيحي @Entity وبالمثل، تستخدم الغرفة أسماء الحقول كأسماء أعمدة في قاعدة البيانات بشكل افتراضي. إذا أردت أن يكون للعمود اسمًا مختلفًا، التعليق التوضيحي @ColumnInfo على التعليق التوضيحي الحقل وضبط name الموقع. يوضّح المثال التالي الأسماء المخصّصة لجدول وأعمدته:

Kotlin

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

Java

@Entity(tableName = "users")
public class User {
    @PrimaryKey
    public int id;

    @ColumnInfo(name = "first_name")
    public String firstName;

    @ColumnInfo(name = "last_name")
    public String lastName;
}

ملاحظة: أسماء الجداول والأعمدة في SQLite غير حساسة لحالة الأحرف.

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

يجب أن يحدّد كل كيان في الغرفة مفتاحًا أساسيًا تحدد بشكل فريد كل صف في جدول قاعدة البيانات المقابل. الأكثر والطريقة المباشرة للقيام بذلك هي التعليق التوضيحي على عمود واحد @PrimaryKey:

Kotlin

@PrimaryKey val id: Int

Java

@PrimaryKey
public int id;

ملاحظة: إذا كنت بحاجة إلى غرفة لتخصيص أرقام تعريف تلقائية لمثيلات الكيان، اضبط autoGenerate الموقع الخاص بـ @PrimaryKey إلى true.

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

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

Kotlin

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

Java

@Entity(primaryKeys = {"firstName", "lastName"})
public class User {
    public String firstName;
    public String lastName;
}

تجاهُل الحقول

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

Kotlin

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

Java

@Entity
public class User {
    @PrimaryKey
    public int id;

    public String firstName;
    public String lastName;

    @Ignore
    Bitmap picture;
}

في الحالات التي يكتسب فيها الكيان الحقول من الكيان الرئيسي، عادةً ما يكون أسهل في استخدام سمة ignoredColumns السمة @Entity:

Kotlin

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

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

Java

@Entity(ignoredColumns = "picture")
public class RemoteUser extends User {
    @PrimaryKey
    public int id;

    public boolean hasVpn;
}

توفير إمكانية البحث في الجداول

تتيح الغرفة استخدام عدة أنواع من التعليقات التوضيحية التي تسهّل عليك البحث. للحصول على تفاصيل في جداول قاعدة البيانات لديك. استخدام البحث في النص الكامل ما لم يكن تطبيقك minSdkVersion أقل من 16.

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

إذا كان تطبيقك يتطلب وصولاً سريعًا جدًا إلى معلومات قاعدة البيانات من خلال النص الكامل FTS، والحصول على دعم الكيانات الخاصة بك من خلال جدول افتراضي يستخدم إما امتداد SQLite FTS3 أو FTS4 . لاستخدام هذه الإمكانية، المتوفرة في الغرفة 2.1.0 أو أعلى، أضف @Fts3 أو التعليق التوضيحي @Fts4 لكيان معيّن، كما هو موضّح في مقتطف الرمز التالي:

Kotlin

// Use `@Fts3` only if your app has strict disk space requirements or if you
// require compatibility with an older SQLite version.
@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 use this type and column name. */
    @PrimaryKey @ColumnInfo(name = "rowid") val id: Int,
    @ColumnInfo(name = "first_name") val firstName: String?
)

Java

// Use `@Fts3` only if your app has strict disk space requirements or if you
// require compatibility with an older SQLite version.
@Fts4
@Entity(tableName = "users")
public class User {
    // Specifying a primary key for an FTS-table-backed entity is optional, but
    // if you include one, it must use this type and column name.
    @PrimaryKey
    @ColumnInfo(name = "rowid")
    public int id;

    @ColumnInfo(name = "first_name")
    public String firstName;
}

ملاحظة: تستخدم الجداول التي تستخدم FTS دائمًا مفتاحًا أساسيًا من النوع INTEGER ومع اسم العمود "rowid". إذا كان الكيان المدعوم من جدول FTS يحدد مفتاحًا أساسيًا، يجب استخدام هذَين النوع واسم العمود.

في الحالات التي يدعم فيها الجدول المحتوى بلغات متعددة، استخدم languageId لتحديد العمود الذي يخزِّن معلومات اللغة كل صف:

Kotlin

@Fts4(languageId = "lid")
@Entity(tableName = "users")
data class User(
    // ...
    @ColumnInfo(name = "lid") val languageId: Int
)

Java

@Fts4(languageId = "lid")
@Entity(tableName = "users")
public class User {
    // ...

    @ColumnInfo(name = "lid")
    int languageId;
}

توفّر الغرفة العديد من الخيارات الأخرى لتحديد الكيانات المدعومة بـ FTS، بما في ذلك وترتيب النتائج وأنواع برامج الترميز والجداول المُدارة كمحتوى خارجي. بالنسبة على مزيد من التفاصيل حول هذه الخيارات، يمكنك مراجعة FtsOptions المرجع.

فهرسة أعمدة معينة

إذا كان يجب أن يتوافق تطبيقك مع إصدارات حزمة تطوير البرامج (SDK) التي لا تتوافق مع FTS3 الكيانات المستندة إلى جدول FTS4، لا يزال بإمكانك فهرسة أعمدة معينة في قاعدة البيانات لتسريع استعلاماتك. لإضافة فهارس إلى كيان، يجب تضمين indices داخل موقع @Entity التعليق التوضيحي وسرد أسماء الأعمدة التي تريد تضمينها في الفهرس أو الفهرس المركب. يوضح مقتطف الرمز التالي هذا التعليق التوضيحي المعالجة:

Kotlin

@Entity(indices = [Index(value = ["last_name", "address"])])
data class User(
    @PrimaryKey val id: Int,
    val firstName: String?,
    val address: String?,
    @ColumnInfo(name = "last_name") val lastName: String?,
    @Ignore val picture: Bitmap?
)

Java

@Entity(indices = {@Index("name"),
        @Index(value = {"last_name", "address"})})
public class User {
    @PrimaryKey
    public int id;

    public String firstName;
    public String address;

    @ColumnInfo(name = "last_name")
    public String lastName;

    @Ignore
    Bitmap picture;
}

في بعض الأحيان، يجب أن تكون بعض الحقول أو مجموعات الحقول في قاعدة البيانات فريدة. يمكنك فرض هذه السمة للتفرّد من خلال ضبط unique الموقع الخاص بـ @Index التعليق التوضيحي إلى true. يمنع نموذج التعليمات البرمجية التالي الجدول صفين يحتويان على مجموعة القيم نفسها لـ firstName lastName عمود:

Kotlin

@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?,
    @Ignore var picture: Bitmap?
)

Java

@Entity(indices = {@Index(value = {"first_name", "last_name"},
        unique = true)})
public class User {
    @PrimaryKey
    public int id;

    @ColumnInfo(name = "first_name")
    public String firstName;

    @ColumnInfo(name = "last_name")
    public String lastName;

    @Ignore
    Bitmap picture;
}

تضمين العناصر المستندة إلى القيمة التلقائية

ملاحظة: تم تصميم هذه الميزة للاستخدام فقط في الكيانات المستندة إلى Java. إلى تحقق نفس الوظائف في الكيانات القائمة على Kotlin، إلا أنه من الأفضل استخدام البيانات الصفوف بدلاً من ذلك

في الغرفة 2.1.0 والإصدارات الأحدث، يمكنك استخدام قيمة غير قابلة للتغيير مستندة إلى Java الصفوف، التي تضيف تعليقات توضيحية إليها باستخدام @AutoValue، ككيانات في قاعدة بيانات تطبيقك. هذا النمط يكون الدعم مفيدًا بشكل خاص عندما يتم النظر في حالتين من كيان متساوين إذا كانت أعمدتهما تحتوي على قيم متطابقة.

عند استخدام الفئات التي تمت إضافة تعليقات توضيحية إليها باستخدام @AutoValue ككيانات، يمكنك إضافة تعليقات توضيحية إلى الطرق التجريدية لفئةٍ باستخدام @PrimaryKey و@ColumnInfo و@Embedded @Relation ولكن عند استخدام هذه التعليقات التوضيحية، يجب عليك تضمين تعليق توضيحي @CopyAnnotations في كل مرة حتى يتمكن "الغرفة" من تفسير الطرق عمليات التنفيذ التلقائية بشكل صحيح.

يعرض مقتطف الرمز التالي مثالاً لفئة تم إدخال تعليقات توضيحية عليها باستخدام @AutoValue الذي تتعرّف عليه الغرفة ككيان:

User.java

@AutoValue
@Entity
public abstract class User {
    // Supported annotations must include `@CopyAnnotations`.
    @CopyAnnotations
    @PrimaryKey
    public abstract long getId();

    public abstract String getFirstName();
    public abstract String getLastName();

    // Room uses this factory method to create User objects.
    public static User create(long id, String firstName, String lastName) {
        return new AutoValue_User(id, firstName, lastName);
    }
}