داده ها را با استفاده از موجودیت های اتاق تعریف کنید

وقتی از کتابخانه‌ی پایداری 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()

روم از چندین حاشیه‌نویسی پشتیبانی می‌کند که به شما امکان می‌دهد جزئیات را در جداول پایگاه داده خود جستجو کنید.

پشتیبانی از جستجوی متن کامل

اگر برنامه شما به جستجوی سریع متن کامل (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
)

برای سفارشی‌سازی نحوه توکن‌سازی اطلاعات پایگاه داده در جداول 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
)

روم چندین گزینه دیگر برای تعریف موجودیت‌های پشتیبانی‌شده توسط FTS ارائه می‌دهد، از جمله ترتیب نتایج، حذف ایندکس‌ها از ستون‌ها و جداولی که به عنوان محتوای خارجی مدیریت می‌شوند. برای اطلاعات بیشتر در مورد این گزینه‌ها، به مرجع FtsOptions مراجعه کنید.

ستون‌های خاص ایندکس

اگر از AndroidSQLiteDriver استفاده می‌کنید و نیاز به پشتیبانی از نسخه‌های SDK دارید که از موجودیت‌های جدولی FTS3، FTS4 یا FTS5 پشتیبانی نمی‌کنند، همچنان می‌توانید ستون‌های خاصی را در پایگاه داده فهرست‌بندی کنید تا سرعت پرس‌وجوهای خود را افزایش دهید. اگر از BundledSQLiteDriver استفاده می‌کنید، Room صرف نظر از نسخه SDK اندروید، از تمام نسخه‌های FTS پشتیبانی می‌کند.

برای افزودن اندیس به یک موجودیت، ویژگی 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,
)

بعدی
با استفاده از DAO به داده ها دسترسی پیدا کنید