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

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

ซึ่งหมายความว่าคุณจะใช้เอนทิตีห้องเพื่อกำหนดฐานข้อมูลได้ สคีมาที่ไม่มี ที่กำลังเขียนโค้ด SQL

กายวิภาคของเอนทิตี

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

โค้ดต่อไปนี้เป็นตัวอย่างของเอนทิตีแบบง่ายที่กำหนดตาราง User มีคอลัมน์สำหรับรหัส ชื่อ และนามสกุล

KotlinJava

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

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

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

    public String firstName;
    public String lastName;
}

หมายเหตุ: หากต้องการคงช่องไว้ ห้องแชทต้องมีสิทธิ์เข้าถึงช่องดังกล่าว คุณสามารถตรวจสอบว่าห้องแชท มีสิทธิ์เข้าถึงฟิลด์ด้วยการทำให้ฟิลด์เป็นสาธารณะหรือโดยให้ getter และ ไม่เหมือนกันอย่างไร

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

KotlinJava

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

@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:

KotlinJava

@PrimaryKey val id: Int

@PrimaryKey
public int id;

หมายเหตุ: หากต้องการให้ห้องแชทกำหนดรหัสอัตโนมัติให้กับอินสแตนซ์เอนทิตี ให้ตั้งค่า autoGenerate พร็อพเพอร์ตี้ของ @PrimaryKey ถึง true

กำหนดคีย์หลักแบบผสม

หากต้องการให้ระบุอินสแตนซ์ของเอนทิตีโดยไม่ซ้ำกันด้วยชุดค่าผสมของ หลายคอลัมน์ คุณสามารถกำหนดคีย์หลักแบบผสมโดยสร้างรายการคอลัมน์เหล่านั้น ในส่วน พร็อพเพอร์ตี้ primaryKeys ของ @Entity:

KotlinJava

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

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

ละเว้นช่อง

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

KotlinJava

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

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

    public String firstName;
    public String lastName;

    @Ignore
    Bitmap picture;
}

ในกรณีที่เอนทิตีรับค่าช่องจากเอนทิตีหลัก โดยทั่วไปแล้วจะ วิธีใช้ พร็อพเพอร์ตี้ ignoredColumns ของ แอตทริบิวต์ @Entity:

KotlinJava

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

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

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

    public boolean hasVpn;
}

ให้การสนับสนุนการค้นหาตาราง

Room รองรับคำอธิบายประกอบหลายประเภทที่ช่วยให้คุณค้นหาได้ง่ายขึ้น เพื่อดูรายละเอียดในตารางฐานข้อมูล ใช้การค้นหาข้อความแบบเต็ม ยกเว้นในกรณีที่ minSdkVersion น้อยกว่า 16 ปี

รองรับการค้นหาข้อความแบบเต็ม

หากแอปของคุณต้องเข้าถึงข้อมูลในฐานข้อมูลผ่านข้อความแบบเต็มอย่างรวดเร็ว ค้นหา (FTS) ให้มีเอนทิตีของคุณสนับสนุนโดยตารางเสมือนที่ใช้ ส่วนขยาย FTS3 หรือ FTS4 SQLite หากต้องการใช้ความสามารถนี้ ที่มีให้ใช้ในห้อง 2.1.0 ขึ้นไป ให้เพิ่ม @Fts3 หรือ คำอธิบายประกอบ @Fts4 ไปยังเอนทิตีที่ระบุ ตามที่แสดง ในข้อมูลโค้ดต่อไปนี้

KotlinJava

// 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?
)

// 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 เพื่อระบุคอลัมน์ที่เก็บข้อมูลภาษาสำหรับ แต่ละแถว:

KotlinJava

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

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

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

Room มีตัวเลือกอื่นๆ อีกมากมายสำหรับการกำหนดเอนทิตีที่สนับสนุน FTS ซึ่งรวมถึง การเรียงลำดับผลลัพธ์ ประเภทโทเค็น และตารางที่จัดการเป็นเนื้อหาภายนอก สำหรับ รายละเอียดเพิ่มเติมเกี่ยวกับตัวเลือกเหล่านี้ได้ที่ ข้อมูลอ้างอิง FtsOptions

คอลัมน์เฉพาะดัชนี

หากแอปต้องรองรับเวอร์ชัน SDK ที่ไม่รองรับ FTS3 หรือ เอนทิตีที่ใช้ตาราง FTS4 คุณยังคงจัดทำดัชนีบางคอลัมน์ในฐานข้อมูลได้ เพื่อเร่งการค้นหาให้เร็วขึ้น หากต้องการเพิ่มดัชนีในเอนทิตี ให้ใส่ indices ภายในพร็อพเพอร์ตี้ @Entity คำอธิบายประกอบ ซึ่งแสดงชื่อของคอลัมน์ที่คุณต้องการรวมไว้ในดัชนี หรือ ดัชนีผสม ข้อมูลโค้ดต่อไปนี้แสดงคำอธิบายประกอบนี้ กระบวนการ:

KotlinJava

@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?
)

@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 ตัวอย่างโค้ดต่อไปนี้ช่วยป้องกันไม่ให้ตารางมี 2 แถวที่มีชุดค่าเดียวกันสำหรับ firstName และ lastName คอลัมน์:

KotlinJava

@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?
)

@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;
}

รวมออบเจ็กต์ที่อิงตาม AutoValue

หมายเหตุ: ความสามารถนี้ออกแบบมาเพื่อใช้ในเอนทิตีที่ใช้ Java เท่านั้น ถึง ได้ฟังก์ชันเดียวกันในเอนทิตีที่ใช้ Kotlin ข้อมูล ชั้นเรียน แทน

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

เมื่อใช้คลาสที่มีคำอธิบายประกอบด้วย @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);
    }
}