Links​

Many-to-one​

Many-to-one relationships typically represent concepts like ownership, membership, or hierarchies. For example, Person and Shirt. One person may own many shirts, and a shirt is (usually) owned by just one person.

type Person {
  required name: str
}

type Shirt {
  required color: str;
  owner: Person;
}

Since links are single by default, each Shirt only corresponds to one Person. In the absence of any exclusivity constraints, multiple shirts can link to the same Person. Thus, we have a one-to-many relationship between Person and Shirt.

When fetching a Person, it’s possible to deeply fetch their collection of Shirts by traversing the Shirt.owner link in reverse. This is known as a backlink; read the select docs to learn more.

One-to-many​

Conceptually, one-to-many and many-to-one relationships are identical; the “directionality” of a relation is just a matter of perspective. Here, the same “shirt owner” relationship is represented with a multi link.

type Person {
  required name: str;
  multi shirts: Shirt {
    # ensures a one-to-many relationship
    constraint exclusive;
  }
}

type Shirt {
  required color: str;
}

Under the hood, a multi link is stored in an intermediate association table, whereas a single link is stored as a column in the object type where it is declared.

type Post {
  required author: User;
}

type User {
  multi posts := (.<author[is Post])
}

One-to-one​

Under a one-to-one relationship, the source object links to a single instance of the target type, and vice versa. As an example consider a schema to represent assigned parking spaces.

type Employee {
  required name: str;
  assigned_space: ParkingSpace {
    constraint exclusive;
  }
}

type ParkingSpace {
  required number: int64;
}

All links are single unless otherwise specified, so no Employee can have more than one assigned_space. Moreover, the exclusive constraint guarantees that a given ParkingSpace can’t be assigned to multiple employees at once. Together the single link and exclusivity constraint constitute a one-to-one relationship.

Many-to-many​

A many-to-many relation is the least constrained kind of relationship. There is no exclusivity or cardinality constraints in either direction. As an example consider a simple app where a User can “like” their favorite Movies.

type User {
  required name: str;
  multi likes: Movie;
}
type Movie {
  required title: str;
}

A user can like multiple movies. And in the absence of an exclusive constraint, each movie can be liked by multiple users. Thus this is a many-to-many relationship.

type User {
  required name: str;
  multi watch_history: Movie {
    seen_at: datetime;
  };
}
type Movie {
  required title: str;
}

type User {
  required name: str;
  multi watch_history: Movie {
    seen_at: array<datetime>;
  };
}
type Movie {
  required title: str;
}

type User {
  required name: str;
  multi watch_history := .<user[is WatchHistory];
}
type Movie {
  required title: str;
}
type WatchHistory {
  required user: User;
  required movie: Movie;
  seen_at: datetime;
}

Inserting and updating link properties​

To add a link with a link property, add the link property to a shape on the linked object being added. Be sure to prepend the link property’s name with @.

insert Person {
  name := "Bob",
  family_members := (
    select detached Person {
      @relationship := "sister"
    }
    filter .name = "Alice"
  )
};

The shape could alternatively be included on an insert if the object being linked (the Person named “Alice” in this example) is being inserted as part of the query. If the outer person (“Bob” in the example) already exists and only the links need to be added, this can be done in an update query instead of an insert as shown in the example above.

Updating a link’s property is similar to adding a new one except that you no longer need to select from the object type being linked: you can instead select the existing link on the object being updated because the link has already been established. Here, we’ve discovered that Alice is actually Bob’s step-sister, so we want to change the link property on the already-established link between the two:

update Person
filter .name = "Bob"
set {
  family_members := (
    select .family_members {
      @relationship := "step-sister"
    }
    filter .name = "Alice"
  )
};

Using select .family_members here with the shape including the link property allows us to modify the link property of the existing link.

# 🚫 Does not work
insert Movie {
  title := 'The Incredible Hulk',
  characters := {(
      select Person {
        @character_name := 'The Hulk'
      } filter .name = 'Mark Ruffalo'
    ),
    (
      select Person {
        @character_name := 'Abomination'
      } filter .name = 'Tim Roth'
    )}
};

# ✅ Works!
insert Movie {
  title := 'The Incredible Hulk',
  characters := assert_distinct((
    with actors := {
      ('The Hulk', 'Mark Ruffalo'),
      ('Abomination', 'Tim Roth')
    },
    for actor in actors union (
      select Person {
        @character_name := actor.0
      } filter .name = actor.1
    )
  ))
};

Querying link properties​

To query a link property, add the link property’s name prepended with @ to a shape on the link.

db> 
... 
... 
... 
... 
... 
... 

select Person {
  name,
  family_members: {
    name,
    @relationship
  }
};

{
  default::Person {name: 'Alice', family_members: {}},
  default::Person {
    name: 'Bob',
    family_members: {
      default::Person {name: 'Alice', @relationship: 'step-sister'}
    }
  },
}

Target deletion​

Target deletion policies determine what action should be taken when the target of a given link is deleted. They are declared with the on target delete clause.

type MessageThread {
  title: str;
}

type Message {
  content: str;
  chat: MessageThread {
    on target delete delete source;
  }
}

The Message.chat link in the example uses the delete source policy. There are 4 available target deletion policies.

• restrict (default) - Any attempt to delete the target object immediately raises an exception.

• delete source - when the target of a link is deleted, the source is also deleted. This is useful for implementing cascading deletes.

  There is a limit to the depth of a deletion cascade due to an upstream stack size limitation.

• allow - the target object is deleted and is removed from the set of the link targets.

• deferred restrict - any attempt to delete the target object raises an exception at the end of the transaction, unless by that time this object is no longer in the set of link targets.

Source deletion​

Source deletion policies determine what action should be taken when the source of a given link is deleted. They are declared with the on source delete clause.

There are 3 available source deletion policies:

• allow - the source object is deleted and is removed from the set of the link’s source objects.

• delete target - when the source of a link is deleted, the target is unconditionally deleted.

• delete target if orphan - the source object is deleted and the target object is unconditionally deleted unless the target object is linked to by another source object via the same link.

type MessageThread {
  title: str;
  multi messages: Message {
    on source delete delete target;
  }
}

type Message {
  content: str;
}

Under this policy, deleting a MessageThread will unconditionally delete its messages as well.

To avoid deleting a Message that is linked to by other MessageThread objects via their message link, append if orphan to that link’s deletion policy.

type MessageThread {
  title: str;
  multi messages: Message {
    on source delete delete target;
    on source delete delete target if orphan;
  }
}

type Channel {
  title: str;
  multi messages: Message {
    on target delete allow;
  }
}

type Channel {
  title: str;
  multi messages: Message {
    on target delete allow;
  }
}