Constraints

This section assumes a basic understanding of EdgeQL.

Constraints gives users fine-grained control over which data is considered valid. The can be defined on properties, links, object types, and custom scalars.

Below is a simple property constraint.

type User {
  required property username -> str {
    constraint exclusive;
  }
}

This example uses a built-in constraint, exclusive. Refer to the table below for a complete list; click the name of a given constraint for the full documentation.

The expression constraint is used to define custom constraint logic. Inside custom constraints, the keyword __subject__ can used to reference the value being constrained.

Constraints on properties

The constraint below uses the built-in len() function, which returns the length of a string.

type User {
  required property username -> str {
    # usernames must be unique
    constraint exclusive;
    # max length (built-in)
    constraint max_len_value(25);
  };
}

Custom constraints

The expression constraint is used to define custom constraint logic. Inside custom constraints, the keyword __subject__ can used to reference the value being constrained.

type User {
  required property username -> str {
    # max length (as custom constraint)
    constraint expression on (len(__subject__) <= 25);
  };
}

Constraints on object types

Constraints can be defined on object types. This is useful when the constraint logic must reference multiple links or properties.

Inside an object type declaration, you can omit __subject__ and simple refer to properties with the leading dot notation (e.g. .<name>).

type ConstrainedVector {
  required property x -> float64;
  required property y -> float64;
  constraint expression on (
    .x ^ 2 + .y ^ 2 <= 25
  );
}

Note that the constraint expression cannot contain arbitrary EdgeQL! Due to how constraints are implemented, you can only reference single (non-multi) properties and links defined on the object type.

# Not valid!
type User {
  required property username -> str;
  multi link friends -> User;
  # ❌ constraints cannot contain paths with more than one hop
  constraint expression on ('bob' in .friends.username);
}

Computed constraints

Constraints can be defined on computed properties.

type User {
  required property username -> str;
  required property clean_username := str_trim(str_lower(.username));
  constraint exclusive on (.clean_username);
}

Composite constraints

To define a composite constraint, create an exclusive constraint on a tuple of properties or links.

type User {
  property username -> str;
}
type BlogPost {
  property title -> str;
  link author -> User;
  constraint exclusive on ((.title, .author));
}

Partial constraints

New

Constraints on object types can be made partial, so that they don’t apply when some condition holds.

type User {
  required property username -> str;
  property deleted -> bool;
  # Not deleted usernames must be unique
  constraint exclusive on (.username) except (.deleted);
}

Constraints on links

When defining a constraint on a link, __subject__ refers to the link itself. This is commonly used add constraints to link properties.

type User {
  property name -> str;
  multi link friends -> User {
    single property strength -> float64;
    constraint expression on (
      __subject__@strength >= 0
    );
  }
}

Constraints on custom scalars

Custom scalar types can be constrained.

scalar type username extending str {
  constraint regexp(r'^[A-Za-z0-9_]{4,20}$');
}

Note: you can’t use exclusive constraints on custom scalar types, as the concept of exclusivity is only defined in the context of a given object type.

Use expression constraints to declare custom constraints using arbitrary EdgeQL expressions. The example below uses the built-in str_trim() function.

scalar type title extending str {
  constraint expression on (
    __subject__ = str_trim(__subject__)
  );
}

︙