Define data using Room entities

When you use the Room persistence library to store your app's data, you define entities to represent the objects that you want to store. Each entity corresponds to a table in the associated Room database, and each instance of an entity represents a row of data in the corresponding table.

Using Room entities lets you define your database schema without writing any SQL code.

Anatomy of an entity

You define each Room entity as a class annotated with @Entity. A Room entity includes properties for each column in the corresponding table in the database, including one or more columns that make up the primary key.

The following code is an example of an entity that defines a User table with columns for ID, first name, and last name:

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

By default, Room uses the class name as the database table name. If you want the table to have a different name, set the tableName property of the @Entity annotation. Similarly, Room uses the property names as column names in the database by default. If you want a column to have a different name, add the @ColumnInfo annotation to the property and set the name property. The following example shows custom names for a table and its columns:

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

Define a primary key

You must define a primary key for each Room entity to uniquely identify each row in the corresponding database table. To do this, annotate a single column with @PrimaryKey:

@PrimaryKey val id: Int

Define a composite primary key

If you need instances of an entity to be uniquely identified by a combination of multiple columns, you can define a composite primary key by listing those columns in the primaryKeys property of @Entity:

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

Ignore properties

By default, Room creates a column for each property defined in the entity. To prevent Room from persisting a property, annotate it with @Ignore:

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

If an entity inherits properties from a parent entity, use the 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 supports several annotations that let you search for details in your database tables.

Support full-text search

If your app requires fast full-text search (FTS), back your entities with a virtual table. Use the FTS3 or FTS4 SQLite extension or the FTS5 SQLite extension.

To use this capability, add the @Fts3, @Fts4, or @Fts5 annotation to an entity.

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

To customize how database information is tokenized in FTS tables, use the tokenizer option. Room provides several built-in tokenizers through FtsOptions, including TOKENIZER_SIMPLE, TOKENIZER_PORTER, and 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 provides several other options for defining FTS-backed entities, including result ordering, removing indexes from columns, and tables managed as external content. For more information about these options, see the FtsOptions reference.

Index specific columns

If you're using AndroidSQLiteDriver and you need to support SDK versions that don't support FTS3-, FTS4-, or FTS5-table-backed entities, you can still index certain columns in the database to speed up your queries. If you use BundledSQLiteDriver, Room supports all FTS versions regardless of the Android SDK version.

To add indexes to an entity, include the indices property in the @Entity annotation. List the column names to include in the index or composite index. The following code snippet shows how to add indexes:

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

Sometimes, certain columns or groups of columns in a database need to contain unique values. To enforce this uniqueness, set the unique property of an @Index annotation to true. The following code sample shows how to enforce this uniqueness:

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

Next
Access data using DAOs