Entity

Entities in Rell are persistent data structures mapped to database tables rather than residing solely in memory. This mapping provides persistent storage and means they are created and deleted explicitly using the create and delete expressions. In contrast, structs in Rell are temporary in-memory data structures used only during code execution.

A variable of an entity type holds the ID (primary key) of the corresponding database record—not the actual attribute values.

entity company {
    name: text;
    address: text;
}

entity user {
    first_name: text;
    last_name: text;
    year_of_birth: integer;
    mutable salary: integer;
}

If the attribute name is not explicitly specified, it defaults to the attribute type.

entity user {
    name;       // built-in type "name"
    company;    // user-defined type "company" (error if no such type exists)
}

Attributes may also have default values applied when an entity is created but not explicitly specified:

entity user {
    home_city: text = 'New York';
}

You can access an entity’s primary key using the implicit rowid attribute:

val u = user @ { .name == 'Bob' };
print(u.rowid);

val alice_id = user @ { .name == 'Alice' } ( .rowid );
print(alice_id);

Unique keys and indices

Entities in Rell can use key and index declarations to ensure data integrity and enable efficient querying:

• Keys: A key uniquely identifies an entity. Declaring a set of attributes as a key guarantees that no two entity records share the same combination of values, thus preventing duplicates.
• Indices: An index provides fast access to entities based on specific attributes. Think of an index as a pointer that quickly locates the relevant data in a table.

For example:

entity user {
    name: text;
    address: text;
    key name;
    index address;
}

Keys and indices can also span multiple attributes. In the following example, while many records may share the same first_name or last_name, the combination must be unique:

entity user {
    first_name: text;
    last_name: text;
    key first_name, last_name;
}

You can specify mutability and even set default values within a key or index clause:

entity address {
    index mutable city: text = 'Rome';
}

note

Mutating an indexed field may be slow if there are many rows in the table.

It is also possible to combine attribute definitions with key or index clauses, although such combined definitions have restrictions (for example, you cannot specify mutable):

entity user {
    key first_name: text, last_name: text;
    index address: text;
}

Relations

Relations in Rell define how entities are connected in the database. They help model associations between entities, ensure data integrity, and support efficient queries. Rell supports several types of relations:

One-to-one

A one-to-one relation ensures that a record in one entity is linked to a single record in another entity. This is useful when each entity must have a unique association with another.

For example, if each user should have a unique residence address:

entity residence {
    key user;
    key address;  // Each address is associated with at most one user
}

Functions might be defined as follows (each will return either a single record or none):

// Returns the unique address associated with a given user.
function get_address(user): address? = residence @? { user }.address; // returns 0 or 1 address

// Returns the unique user associated with a given address.
function get_user(address): user? = residence @? { address }.user;   // returns 0 or 1 user

One-to-many

A one-to-many (or many-to-one) relationship means that a single record in one entity can be linked to multiple records in another. This is appropriate when one entity needs multiple associations with another.

For example, if a user can have multiple residences (addresses) but each residence belongs to only one user:

entity residence {
  index user;    // Non-unique: a user can appear in multiple residence records.
  key address;   // Unique: each address appears in only one residence record, meaning it is associated with exactly one user.
}

The functions are described as follows:

// Returns all addresses associated with a given user.
function get_addresses(user): list<address> = residence @* { user }.address;

// Returns the unique user associated with a given address.
function get_user(address): user? = residence @? { address }.user;

This setup allows a user to have multiple addresses while each address is linked to a single user.

To reverse the relationship—allowing multiple users to share a single address—you simply swap the field roles:

entity residence {
  key user;    // Unique: each user is stored only once.
  index address;   // Non-unique: an address can be shared by multiple users.
}

In this reversed configuration, a query for an address would return multiple users sharing that address.

Many-to-many

A many-to-many relation allows multiple records in one entity to be linked to multiple records in another. This is useful when associations between entities are complex.

For example, if users can have multiple addresses and each address can be shared by multiple users:

entity user {
  key pubkey;
  index name;
}

entity address {
  key pubkey;
  street: text;
}

entity residence {
  key user, address;
}

Here, the composite key (user, address) guarantees that each pairing is unique, supporting many-to-many associations.

Functions for a many-to-many relationship might be:

// Both functions return lists of records since multiple associations exist.
function get_addresses(user): list<address> = residence @* { user }.address;
function get_users(address): list<user> = residence @* { address }.user;

info

For more on relationships in Rell, consider exploring our course Understand Relationships in Rell.

Annotations

You can transform entities into immutable historical records by applying the @log annotation:

@log entity user {
    name: text;
}

The @log annotation:

• Adds transaction context: Automatically adds a transaction attribute (of type transaction) to capture the entity’s creation context.
• Enforces immutability: Prevents modifications or deletion, preserving historical data integrity.

Changing entity definitions

When you start a Rell dapp, the database schema is updated: tables for new entities and objects are created, and existing ones are altered. However, there are limitations to modifying entities once deployed.

Compatible changes

• Adding attributes with defaults: New attributes can be added with default values; existing records will receive these defaults.
• Adding attributes to empty tables: If no data exists, additional attributes (even without defaults) can be freely added.
• Removing attributes: You may remove attributes as needed.
• Changing attribute mutability: For entities not annotated with @log, you can change an attribute’s mutability (from mutable to non-mutable or vice versa).

Incompatible changes

• Attribute type changes: Altering an attribute’s type may cause compatibility issues or data corruption. Plan your schema carefully.
• Adding/Removing @log annotation: Once an entity is marked with @log for immutable history, you cannot remove it or add it to an existing entity.