تعریف داده‌ها بااستفاده از نهادهای Room

وقتی از کتابخانه ماندگاری Room برای ذخیره کردن داده‌های برنامه‌تان استفاده می‌کنید، نهادهایی را تعریف می‌کنید که نشان‌دهنده اشیایی هستند که می‌خواهید ذخیره کنید. هر نهاد با جدولی در پایگاه داده Room مرتبط مطابقت دارد، و هر نمونه از یک نهاد نشان‌دهنده ردیفی از داده‌ها در جدول مربوطه است.

استفاده از نهادهای Room به شما امکان می‌دهد طرحواره پایگاه داده خود را بدون نوشتن کد SQL تعریف کنید.

تشریح یک نهاد

هر نهاد «اتاق» را به‌عنوان کلاسی که با @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
)

تعریف کلید اصلی

باید برای هر نهاد «اتاق» کلید اصلی تعریف کنید تا هر ردیف در جدول پایگاه داده مربوطه به‌طور یکتا شناسایی شود. برای انجام این کار، یک ستون را با @PrimaryKey حاشیه‌نویسی کنید:

@PrimaryKey val id: Int

تعریف کلید اصلی مرکب

اگر نیاز دارید نمونه‌های یک نهاد با ترکیبی از چندین ستون به‌صورت یکتا شناسایی شوند، می‌توانید با فهرست کردن آن ستون‌ها در ملک primaryKeys از @Entity، یک کلید اصلی مرکب تعریف کنید:

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

نادیده گرفتن خصوصیت‌ها

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

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

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

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

اگر از AndroidSQLiteDriver استفاده می‌کنید و باید از نسخه‌های SDK پشتیبانی کنید که از نهادهای پشتیبانی‌شده با جدول FTS3،‏ FTS4، یا FTS5 پشتیبانی نمی‌کنند، همچنان می‌توانید ستون‌های خاصی را در پایگاه داده نمایه کنید تا سرعت پُرسمان‌هایتان را افزایش دهید. اگر از BundledSQLiteDriver استفاده می‌کنید، Room از همه نسخه‌های FTS بدون درنظر گرفتن نسخه «کیت توسعه نرم‌افزار 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,
)

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