Links​

Defining links​

type Person {
  best_friend: Person;
}

Links are directional; they have a source (the object type on which they are declared) and a target (the type they point to).

Link cardinality​

All links have a cardinality: either single or multi. The default is single (a “to-one” link). Use the multi keyword to declare a “to-many” link.

type Person {
  multi friends: Person;
}

On the other hand, backlinks work in reverse to find objects that link to the object, and thus assume multi as a default. Use the single keyword to declare a “to-one” backlink.

type Author {
  link posts := .<authors[is Article];
}

type CompanyEmployee {
  single link company := .<employees[is Company];
}

Required links​

All links are either optional or required; the default is optional. Use the required keyword to declare a required link. A required link must point to at least one target instance. In this scenario, every Person must have a best_friend:

type Person {
  required best_friend: Person;
}

Links with cardinality multi can also be required; required multi links must point to at least one target object.

type Person {
  name: str;
}

type GroupChat {
  required multi members: Person;
}

In this scenario, each GroupChat must contain at least one person. Attempting to create a GroupChat with no members would fail.

Exclusive constraints​

You can add an exclusive constraint to a link to guarantee that no other instances can link to the same target(s).

type Person {
  name: str;
}

type GroupChat {
  required multi members: Person {
    constraint exclusive;
  }
}

In the GroupChat example, the GroupChat.members link is now exclusive. Two GroupChat objects cannot link to the same Person; put differently, no Person can be a member of multiple GroupChat.

Modeling relations​

By combinining link cardinality and exclusivity constraints, we can model every kind of relationship: one-to-one, one-to-many, many-to-one, and many-to-many.

type Person {
  required name: str
}

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

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

type Shirt {
  required color: str;
}

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

type ParkingSpace {
  required number: int64;
}

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

Default values​

Like properties, links can declare a default value in the form of an EdgeQL expression, which will be executed upon insertion. In the example below, new people are automatically assigned three random friends.

type Person {
  required name: str;
  multi friends: Person {
    default := (select Person order by random() limit 3);
  }
}

Link properties​

Like object types, links in EdgeDB can contain properties. Link properties can be used to store metadata about links, such as when they were created or the nature/strength of the relationship.

type Person {
  name: str;
  multi family_members: Person {
    relationship: str;
  }
}

type Person {
  name: str;
  multi friends: Person {
    introduced_by: Person;
  }
}

Above, we model a family tree with a single Person type. The Person. family_members link is a many-to-many relation; each family_members link can contain a string relationship describing the relationship of the two individuals.

Due to how they’re persisted under the hood, link properties must always be single and optional.

In practice, link properties are most useful with many-to-many relationships. In that situation there’s a significant difference between the relationship described by the link and the target object. Thus it makes sense to separate properties of the relationships and properties of the target objects. On the other hand, for one-to-one, one-to-many, and many-to-one relationships there’s an exact correspondence between the link and one of the objects being linked. In these situations any property of the relationship can be equally expressed as the property of the target object (for one-to-many and one-to-one cases) or as the property of the source object (for many-to-one and one-to-one cases). It is generally advisable to use object properties instead of link properties in these cases due to better ergonomics of selecting, updating, and even casting into json when keeping all data in the same place rather than spreading it across link and object properties.

Deletion policies​

Links can declare their own deletion policy. There are two kinds of events that might trigger these policies: target deletion and source deletion.

type MessageThread {
  title: str;
}

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

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

type Message {
  content: str;
}

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;
  }
}

Polymorphic links​

Links can have abstract targets, in which case the link is considered polymorphic. Consider the following schema:

abstract type Person {
  name: str;
}

type Hero extending Person {
  # additional fields
}

type Villain extending Person {
  # additional fields
}

The abstract type Person has two concrete subtypes: Hero and Villain. Despite being abstract, Person can be used as a link target in concrete object types.

type Movie {
  title: str;
  multi characters: Person;
}

In practice, the Movie.characters link can point to a Hero, Villain, or any other non-abstract subtype of Person. For details on how to write queries on such a link, refer to the Polymorphic Queries docs

Abstract links​

It’s possible to define abstract links that aren’t tied to a particular source or target. If you’re declaring several links with the same set of properties, annotations, constraints, or indexes, abstract links can be used to eliminate repetitive SDL.

abstract link link_with_strength {
  strength: float64;
  index on (__subject__@strength);
}

type Person {
  multi friends: Person {
    extending link_with_strength;
  };
}