Room 항목을 사용하여 데이터 정의

Room 지속성 라이브러리를 사용하여 앱 데이터를 저장할 때는 저장하려는 객체를 나타내는 항목을 정의해야 합니다. 각 항목은 연결된 Room 데이터베이스의 테이블에 상응하고, 항목의 각 인스턴스는 상응하는 테이블의 데이터 행 하나를 나타냅니다.

Room 항목을 사용하면 SQL 코드를 작성하지 않고도 데이터베이스 스키마를 정의할 수 있습니다.

항목 분석

각 Room 항목을 @Entity로 주석 처리된 클래스로 정의합니다. Room 항목에는 기본 키를 구성하는 하나 이상의 열을 비롯하여 데이터베이스의 상응하는 테이블에 있는 각 열의 속성이 포함되어 있습니다.

다음 코드는 ID, 이름, 성의 열이 있는 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()

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를 사용하고 FTS3, FTS4 또는 FTS5 테이블 지원 항목을 지원하지 않는 SDK 버전을 지원해야 하는 경우에도 여전히 데이터베이스에 있는 특정 열의 색인을 생성하여 쿼리 속도를 높일 수 있습니다. BundledSQLiteDriver를 사용하는 경우 Room은 Android 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를 사용하여 데이터 액세스