Light
Dark
System
v4latest
v5dev
v4latest
v3
v2
v1

Properties

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

Copy
type Player {
  email: str;
  points: int64;
  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.

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

Copy
type User {
  required email: str;
}

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

Copy
type User {

  # single isn't necessary here
  # properties are single by default
  single name: str;

  # an unordered set of strings
  multi nicknames: str;

  # an unordered set of string arrays
  multi 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.

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

Copy
type Player {
  required points: int64 {
    default := 0;
  }

  required latitude: float64 {
    default := (360 * random() - 180);
  }
}

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.

Copy
type User {
  required external_id: uuid {
    readonly := true;
  }
}

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

Copy
type BlogPost {
  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 ]+$');
  }

  status: str {
    constraint one_of('Draft', 'InReview', 'Published');
  }

  upvotes: int64 {
    constraint min_value(0);
    constraint max_value(9999);
  }
}

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

Copy
type BlogPost {
  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.

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

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

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.

Copy
abstract property email_prop {
  annotation title := 'An email address';
  readonly := true;
}

type Student {
  # inherits annotations and "readonly := true"
  email: str {
    extending email_prop;
  };
}
Light
Dark
System

We use ChatGPT with additional context from our documentation to answer your questions. Not all answers will be accurate. Please join our Discord if you need more help.