Introduction to Tables & Entities

This section covers how to create tables and entities for your Room database.

Databases contain tables that store data. You store data in tables by creating entities, which are objects in the table that describe how the table looks and the properties in the table. The table becomes a container for your data. Tables store data in rows and columns. Each row has one or more columns that store data. An example of a user table is shown below:

In the example above, the table has four columns, namely: id, name, email, and age. Each row in the table represents a different user. The first row represents a user with the id as 1, name as John, email as john@mail.com, and age as 25. In this table, the id column is the primary key that uniquely identifies each row in the table. You can populate the table with as many rows as you want. The user table example above has three rows.

Each column in the table must have a data type that specifies the type of data that can be stored in the column. Common data types include INTEGER, TEXT, DATETIME, FLOAT, among others, depending on the database you’re using.

Each table must have a primary key that uniquely identifies each row in the table. You can either autogenerate the primary key or specify the primary key yourself if you have a column value that will be unique for each row.

A primary key also helps you create relationships between tables by defining foreign keys. Foreign keys reference the primary key in another table. Still using the user table, you can reference the id column in another table, as shown below:

In the example above, the table stores notes for each user. The table has four columns, namely: id, user_id, title, and content. The user_id column references the id column in the user table. This is an example of a one-to-many relationship between the user table and the notes table. This means that one user can have many notes but each note belongs to only one user.

The user_id column in the notes table is a foreign key that references the id column in the user table. This relationship allows you to associate notes with users. This ensures you don’t have to store the user information in the notes table or the note information in the user table. You can use the value in the user_id column to get the user information from the user table. This way, your tables are lightweight. They don’t have a lot of redundant data.

Now that you understand how tables work, you’ll learn about entities in the next section. Room uses entities to represent tables in the database.

An entity represents a table’s rows in a database. Each property of the entity corresponds to a column in the table. An entity is a data class that helps define the schema of the table, or how all the data in the database is organized and related. The entity is annotated with the @Entity annotation. Take a look at an example of an entity:

@Entity(tableName = "notes")
@Serializable
data class NoteEntity(
  @PrimaryKey(autoGenerate = true)
  val id: Int = 0,
  val title: String,
  val description: String,
  val timestamp: Long,
  val priority: String,
  val noteLocation: String
)

This is a Kotlin data class, but it has the following annotations:

• @Entity(tableName = "notes"): The @Entity annotation tells Room that the class represents a table in the database. The tableName attribute specifies the name of the table. If you don’t specify a name, the table name will be the same as the class name.
• @PrimaryKey(autoGenerate = true): This annotation specifies the primary key for the table. A primary key is a unique identifier for each row in the table. The autoGenerate attribute is set to true which means that the primary key will be automatically generated.

Other annotations that you can use in your entities include:

• @ColumnInfo(name = "column_name"): This annotation allows you to specify the name of the column in the table. You use this annotation when you want the column name to be different from the property name.
• @Ignore: This annotation tells Room to ignore the property in the entity. By default, Room creates a column for each property in the entity. If you want to ignore a property, you can add it to this attribute.
• @Embedded: This annotation allows you to embed another class in the entity. You use this annotation when you want to store a complex object, such as another data class, in the database.

Additionally, inside the @Entity annotation, you can specify the following attributes:

• indices: This attribute allows you to specify the columns that you want to index. Indexing columns can improve the performance of your queries.
• foreignKeys: This attribute allows you to specify foreign keys for the table. You use this attribute when you want to enforce referential integrity between tables.
• primaryKeys: You use this attribute when you want your entity to be uniquely identified by multiple columns. You add the composite primary key columns to this attribute.
• inheritSuperIndices: This attribute allows you to specify index inheritance. You can choose whether the index of the superclass is inherited or not.
• ignoredColumns: This attribute allows you to specify the columns that you want to ignore. This is normally helpful when you want to ignore columns inherited from a parent class.