@unique annotation

The @unique annotation is used to specify unique attributes for entities and relations.

Syntax

Syntax
<type label> owns <attribute type label> @unique;

The @unique annotation does not accept any arguments.

Usage

The @unique annotation can be defined for an ownership to put the unique constraint on it. The unique constraint means that no two instances of the owner type (owners) can have instances of the attribute type (attributes) with the same value. That makes every owned attribute unique by value among all instances of the owner type and its subtypes.

For example, the following statement defines that every user should have a unique phone:

#!test[schema]
define
  entity user owns phone @unique;
  attribute phone value string;

With this constraint, no instance of user can share the same phone value.

Subtyping

The unique constraint would also affect the following schema extension:

#!test[schema]
define
  entity uk-user sub user, owns uk-phone;
  entity usa-user sub user, owns usa-phone;
  phone @abstract;
  attribute uk-phone sub phone;
  attribute usa-phone sub phone;

With the unique constraint on the phone, there is a protection ensuring that:

  • Any user can only have one unique phone.

  • A uk-user cannot have a uk-phone with the same value as a usa-user 's usa-phone.

If there is a need to restrict uniqueness within subtypes (e.g., allowing uk-user and usa-user to have phones with overlapping values, but still unique within their respective regions), the unique constraint should be applied directly to the subtype ownerships instead.

Limitations

Cannot be used with the @key annotation as they both produce the unique constraint.

See Supported value types for the list of supported value types.

References

Supported value types

The @unique annotation is applicable only to uniquely hashable value types.

Table 1. Supported value types

Value type

Supported?

Comment

boolean

✓

integer

✓

decimal

✓

string

✓

date

✓

datetime

✓

datetime-tz

✓

duration

✓

double

✗

Constraining double attributes by exact value is error-prone and as such disallowed