Using link properties​

Declaration​

Let’s a create a Person.friends link with a strength property corresponding to the strength of the friendship.

type Person {
  required name: str { constraint exclusive };

  multi friends: Person {
    strength: float64;
  }
}

Constraints​

type Person {
  required name: str { constraint exclusive };

  multi friends: Person {
    strength: float64;
    constraint expression on (
      __subject__@strength >= 0
    );
  }
}

Indexes​

To index on a link property, you must declare an abstract link and extend it.

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

type Person {
  required name: str { constraint exclusive };
  multi friends: Person {
    extending friendship;
  };
}

Conceptualizing link properties​

A good way to conceptualize the difference between a regular property and a link property for object types is that regular properties are used to construct expressions that return object types, while link properties are appended to expressions that return object types to qualify the link.

For example, the properties name and email are used to construct a Person object that is inserted, also returning the same Person object.

insert Person {
  name := "Jane",
  email := "jane@jane.com"
}

If this Person object is inserted while linking it to another Person object we are inserting, we can append a @strength property to the link. @strength is not used to construct a Person, but to quantify the link.

insert Person {
  name := "Bob",
  email := "bob@bob.com",
  friends := (
    insert Person {
      name := "Jane",
      email := "jane@jane.com",
      @strength := 3.14
    }
  )
}

Keep this in mind when reading through the following examples.

Inserting​

The @strength property is specified in the shape of the select subquery. This is only valid in a subquery inside an insert statement.

insert Person {
  name := "Bob",
  friends := (
    select detached Person {
      @strength := 3.14
    }
    filter .name = "Alice"
  )
}

When doing a nested insert, link properties can be directly included in the inner insert subquery. The query below creates a link to a Person object that is being inserted in the same query, along with a link property strength that has a value of 3.14.

insert Person {
  name := "Bob",
  friends := (
    insert Person {
      name := "Jane",
      @strength := 3.14
    }
  )
}

Similarly, with can be used to capture an expression returning an object type, after which a link property can be added when linking it to another object type:

with
_friends := (
  insert Person {
   name := "Alice"
  } unless conflict on .name
  else (select Person filter .name = "Alice" limit 1 )
)
insert Person {
  name := "Bob",
  friends := _friends {
    @strength := 3.14
  }
};

Updating​

update Person
filter .name = "Bob"
set {
  friends += (
    select .friends {
      @strength := 3.7
    }
    filter .name = "Alice"
  )
};

The example updates the @strength property of Bob’s friends link to Alice to 3.7.

In the context of multi links the += operator works like an an insert/update operator.

To update one or more links in a multi link, you can select from the current linked objects, as the example does. Use a detached selection if you want to insert/update a wider selection of linked objects instead.

Querying​

edgedb> 
....... 
....... 
....... 
....... 
....... 
....... 

select Person {
  name,
  friends: {
    name,
    @strength
  }
};

{
  default::Person {name: 'Alice', friends: {}},
  default::Person {
    name: 'Bob',
    friends: {
      default::Person {name: 'Alice', @strength: 3.7}
    }
  },
}

# 🚫 Does not work
insert Movie {
  title := 'The Incredible Hulk',
  actors := {(
      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',
  actors := assert_distinct((
    with characters := {
      ('The Hulk', 'Mark Ruffalo'),
      ('Abomination', 'Tim Roth')
    },
    for character in characters union (
      select Person {
        @character_name := character.0
      } filter .name = character.1
    )
  ))
};

type Person {
  required name: str;
  multi follows: Person {
    followed: datetime {
      default := datetime_of_statement();
    };
  };
  multi link followers := .<follows[is Person];
}

select Person {
  name,
  followers: {
    name,
    @followed
  }
};

select Person {
  name,
  followers := .<follows[is Person] {
    name,
    followed := @followed
  }
};