Skip to main content

Documentation Index

Fetch the complete documentation index at: https://archie.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

A Relationship field links a record in one table to a record (or records) in another. Unlike a UUID or a Text field, it doesn’t store a free-form value — it stores a reference to a row in another table and enforces that the reference is valid. When you add a relationship, Archie creates the corresponding inverse field on the other side automatically, so the connection works in both directions. The auto-generated GraphQL API exposes the relationship as a nested field, letting you fetch a record and its related records in a single query.

​
Cardinality

CardinalityWhat it meansExample
One-to-OneRecord A links to exactly one Record B, and vice versa.User ↔ Profile — every user has one profile.
One-to-ManyRecord A is linked to many Record Bs, but each Record B belongs to one Record A.Author ↔ Books — an author writes many books, each book has one author.
For more on choosing cardinality and how Archie models many-to-many connections, see Relationships.

​
Creating a relationship

1

Add a field

On the Schema tab, click + Add Field and pick Relationship from the type dropdown.
2

Open the configuration

Click the configuration icon on the right side of the field row to open the relationship settings.
3

Pick the related table

Choose the target table from the Related Table dropdown.
4

Choose the cardinality

Pick One-to-One or One-to-Many based on how the two tables relate.
5

Mark mandatory if required

Turn on Mandatory if every record must have a related record. Leave it off to allow the link to be empty.
Relationship field type configuration
When you create a relationship, Archie automatically adds the inverse field on the related table — for example, adding author on books also exposes books as a nested field on author. You don’t need to set it up on both sides.

​
How it appears in the API

The relationship is exposed in GraphQL as a nested field. Given an Author with a one-to-many books relationship, you can fetch both in one query: 
query {
  author(id: "...") {
    id
    name
    books {
      id
      title
    }
  }
}
The reverse direction works too — given a book, you can resolve its author: 
query {
  book(id: "...") {
    id
    title
    author {
      id
      name
    }
  }
}
See the GraphQL API Explorer to inspect the generated queries and mutations for your specific tables.

​
Permissions

A relationship field is governed by the read and write permissions on both tables. A user has to be able to read a related table for it to appear in the nested query. Configure this in Role-Based Access.

​
FAQ

Create a join table with one-to-many relationships pointing to each side. For example, a students_courses join table linking students and courses gives you the many-to-many. See Relationships for the full pattern.
The default behavior is to prevent the deletion when there are referencing rows. See Relationships for cascade and nullify options.
No. The relationship field is itself the foreign key — it stores the reference to the related table’s primary key.
Yes. Rename the field on the Schema tab. The GraphQL nested field name updates immediately; any client code that uses the old name will need to be updated.