กำหนดข้อมูลโดยใช้เอนทิตีห้อง

เมื่อใช้ ไลบรารีการคงอยู่ของข้อมูล Room เพื่อจัดเก็บข้อมูลของแอป คุณจะ กำหนดเอนทิตีเพื่อแสดงออบเจ็กต์ที่ต้องการจัดเก็บ โดยแต่ละเอนทิตีจะสอดคล้องกับตารางในฐานข้อมูล Room ที่เชื่อมโยง และแต่ละอินสแตนซ์ของเอนทิตีจะแสดงแถวของข้อมูลในตารางที่เกี่ยวข้อง

การใช้เอนทิตี Room ช่วยให้คุณกำหนดสคีมาของฐานข้อมูล ได้โดยไม่ต้องเขียนโค้ด SQL

โครงสร้างของเอนทิตี

คุณกำหนดเอนทิตี Room แต่ละรายการเป็นคลาสที่มีคำอธิบายประกอบ @Entity เอนทิตี Room จะมีพร็อพเพอร์ตี้สำหรับแต่ละคอลัมน์ในตารางที่เกี่ยวข้องใน ฐานข้อมูล ซึ่งรวมถึงคอลัมน์อย่างน้อย 1 คอลัมน์ที่ประกอบกันเป็นคีย์หลัก

โค้ดต่อไปนี้เป็นตัวอย่างของเอนทิตีที่กำหนดตาราง 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 property of the @Entity annotation:

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
)

หากต้องการปรับแต่งวิธีแยกข้อมูลฐานข้อมูลออกเป็นโทเค็นในตาราง 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 SDK จะเป็นเวอร์ชันใดก็ตาม

หากต้องการเพิ่มดัชนีลงในเอนทิตี ให้ใส่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