Properties

Properties are used to associate primitive data with an object type or link.

type Player {
  property email -> str;
  property points -> int64;
  property is_online -> bool;
}

Properties are associated with a key (e.g. first_name) and a primitive type (e.g. str` ). The term primitive type is an umbrella term that encompasses scalar types like str and bool, enums, arrays, and tuples.

Required properties

Properties can be either optional (the default) or required.

type User {
  required property email -> str;
}

Property cardinality

Properties have a cardinality, either single (the default) or multi. A multi property of type str points to an unordered set of strings.

type User {
  # single isn't necessary here
  # properties are single by default
  single property name -> str;
  # an unordered set of strings
  multi property nicknames -> str;
  # an unordered set of string arrays
  multi property set_of_arrays -> array<str>;
}

Comparison to arrays

The values associated with a multi property are stored in no particular order. If order is important, use an array. Otherwise, multi properties are recommended. For a more involved discussion, see EdgeQL > Sets.

Default values

Properties can have a default value. This default can be a static value or an arbitrary EdgeQL expression, which will be evaluated upon insertion.

type Player {
  required property points -> int64 {
    default := 0;
  }
  required property latitude -> float64 {
    default := (360 * random() - 180);
  }
}

Readonly properties

Properties can be marked as readonly. In the example below, the User.external_id property can be set at the time of creation but not modified thereafter.

type User {
  required property external_id -> uuid {
    readonly := true;
  }
}

Constraints

Properties can be augmented wth constraints. The example below showcases a subset of EdgeDB’s built-in constraints.

type BlogPost {
  property title -> str {
    constraint exclusive; # all post titles must be unique
    constraint min_len_value(8);
    constraint max_len_value(30);
    constraint regexp(r'^[A-Za-z0-9 ]+$');
  }
  property status -> str {
    constraint one_of('Draft', 'InReview', 'Published');
  }
  property upvotes -> int64 {
    constraint min_value(0);
    constraint max_value(9999);
  }
}

You can constrain properties with arbitrary EdgeQL expressions returning bool. To reference to value of the property, use the special scoped keyword __subject__.

type BlogPost {
  property title -> str {
    constraint expression on (
      __subject__ = str_trim(__subject__)
    );
  }
}

The constraint above guarantees that BlogPost.title doesn’t contain any leading or trailing whitespace by checking that the raw string is equal to the trimmed version. It uses the built-in str_trim() function.

For a full reference of built-in constraints, see the Constraints reference.

Annotations

Properties can contain annotations, small human-readable notes. The built-in annotations are title, description, and deprecated. You can declare custom annotation types.

type User {
  property email -> str {
    annotation title := 'Email address';
    annotation description := "The user's email address.";
    annotation deprecated := 'Use NewUser instead.';
  }
}

Abstract properties

Properties can be concrete (the default) or abstract. Abstract properties are declared independent of a source or target, can contain annotations, and can be marked as readonly.

abstract property email_prop {
  annotation title := 'An email address';
  readonly := true;
}
type Student {
  # inherits annotations and "readonly := true"
  property email extending email_prop -> str;
}

Link properties

Properties can also be defined on links. For a full guide, refer to Guides > Using link properties.

︙