Relational

Relational fields create foreign key relationships between collections, linking records together. They define how data in one collection relates to data in another.

Go to Studio → Collections → [Collection Name] → Fields tab → Add Field, then select Relational. To edit an existing field, click the edit action next to it.

View all settings

Setting	Description
Field Name	Text input, required. Unique identifier for the relationship.
Display Label	Text input. Human-readable label shown in forms.
Icon	Icon picker. Visual identifier.
Relational Label	Dropdown. Field from target collection to display. Creates a lookup automatically.
Status	Toggle, defaults to true. Enable or disable the field.
Required	Checkbox. Make the relationship mandatory.
Bidirectional	Checkbox. Makes the relation available in Association and other related fields.
Description	Text area. Documents the relationship's purpose.
Form Visibility	Dropdown. Show in Add, Edit, or Both forms.
DB Field Name	Text input. Custom database column name.

Relation Types

Use the Relation Viewer to select how collections are linked. Each type creates different database structures:

Type	Icon	Description
One to one		Each record links to exactly one record in the target collection. Example: User → Profile
Belongs to		The record belongs to one parent record in the target collection. Example: Book → Author
Many to many		Records on both sides can link to multiple records. Creates a junction table. Example: Students ↔ Courses

Basic Settings

Enter a Field Name using camelCase. The Display Label appears in forms. Set the Relational Label to specify which field from the target collection should display — this automatically creates a lookup field.

Turn on Bidirectional to make this relation available when setting up Association or other relation-related fields in the target collection. If you leave it unchecked, the relation won't show up as an option in those fields.

Relation Viewer

The visual Relation Viewer appears below the basic settings and lets you:

1. Select the relation type using the cards (One to one, Belongs to, Many to many).
2. Choose the target collection — the collection you want to link to.
3. Set the record keys — define the source and target keys for the relationship.
4. Auto-generate name — optionally let Hyper name the relationship automatically.

Naming Relational Aliases

Use descriptive cross-names in camelCase for relation aliases to avoid errors like "Ambiguous table name" in queries or duplicate keys in the generated code.

For example, if you set up a relationship between User and Assignee:

• Use aliases like userHasAssignee and assigneeHasUser.
• Avoid using just the collection name like user or assignee if there could be multiple relationships between these collections.

This prevents collisions when the same collections are linked in multiple ways.

Many-to-Many Setup

For Many to many relationships, you have two options:

• Table auto generated (checked) — Hyper creates and manages the junction table automatically.
• Manual setup (unchecked) — You select an existing collection as the junction table and set:
  • Select collection — Choose the junction collection.
  • Source Field — Field linking to the source collection.
  • Target Field — Field linking to the target collection.

If you enable auto-generation, you can also select an Aggregator Function for the relationship.

Advanced Settings

The Description text area lets you document the relationship's purpose.

Setting	Description
Form Visibility	Choose when this field appears: Add forms, Edit forms, or Both.
DB Field Name	Override the database column name for the foreign key.

Query Filters

The Query Filters tab lets you restrict which related records can be selected:

Setting	Description
Field	Select a field from the target collection to filter on.
Operator	Comparison operator (is equal to, is not equal to, contains, etc.).
Value	The value to compare against.
From Form	Pull the filter value from a form field instead of a static value.
Optional	Make this filter condition optional.

Click Add Filter to add multiple conditions.

Use Cases

• User → Profile — One-to-One relationship for extended user data
• Author → Books — One-to-Many for ownership relationships
• Students ↔ Courses — Many-to-Many for enrollments with junction table
• Order → Customer — Link orders to customer records
• Product → Category — Organize products into categories

Related

• Common Settings — Shared settings reference
• Lookup — For read-only related display
• Association — For aggregating related data