Search...
ctrl/
Light
Dark
System
Sign in

Annotations​

Annotations are named values associated with schema items and are designed to hold arbitrary schema-level metadata represented as a str (unstructured text).

Users can store JSON-encoded data in annotations if they need to store more complex metadata.

Standard annotations​

There are a number of annotations defined in the standard library. The following are the annotations which can be set on any schema item:

  • std::title

  • std::description

  • std::deprecated

For example, consider the following declaration:

Copy
type Status {
  annotation title := 'Activity status';
  annotation description := 'All possible user activities';

  required name: str {
    constraint exclusive
  }
}

And the std::deprecated annotation can be used to mark deprecated items (e.g., str_rpad()) and to provide some information such as what should be used instead.

User-defined annotations​

To declare a custom annotation type beyond the three built-ins, add an abstract annotation type to your schema. A custom annotation could be used to attach arbitrary JSON-encoded data to your schema—potentially useful for introspection and code generation.

Copy
abstract annotation admin_note;

type Status {
  annotation admin_note := 'system-critical';
}

Declaring annotations​

This section describes the syntax to use annotations in your schema.

Syntax​

Abstract annotation form:
abstract [ inheritable ] annotation name
[ "{" annotation-declarations; [...] "}" ] ;

Concrete annotation (same as annotation-declarations) form:
annotation name := value ;

Description​

There are two forms of annotation declarations: abstract and concrete. The abstract annotation form is used for declaring new kinds of annotation in a module. The concrete annotation declarations are used as sub-declarations for all other declarations in order to actually annotate them.

The annotation declaration options are as follows:

abstract

If specified, the annotation will be abstract.

inheritable

If specified, the annotation will be inheritable. The annotations are non-inheritable by default. That is, if a schema item has an annotation defined on it, the descendants of that schema item will not automatically inherit the annotation. Normal inheritance behavior can be turned on by declaring the annotation with the inheritable qualifier. This is only valid for abstract annotation.

name

The name (optionally module-qualified) of the annotation.

value

Any string value that the specified annotation is intended to have for the given context.

The only valid SDL sub-declarations are concrete annotations:

annotation-declarations

Annotations can also have annotations. Set the annotation of the enclosing annotation to a specific value.

DDL commands​

This section describes the low-level DDL commands for creating, altering, and dropping annotations and abstract annotations. You typically don't need to use these commands directly, but knowing about them is useful for reviewing migrations.

Create abstract annotation​

Define a new annotation.

[ with with-item [, ...] ]
create abstract [ inheritable ] annotation name
[
  "{"
    create annotation annotation-name := value ;
    [...]
  "}"
] ;

Description​

The command create abstract annotation defines a new annotation for use in the current Gel database.

If name is qualified with a module name, then the annotation is created in that module, otherwise it is created in the current module. The annotation name must be distinct from that of any existing schema item in the module.

The annotations are non-inheritable by default. That is, if a schema item has an annotation defined on it, the descendants of that schema item will not automatically inherit the annotation. Normal inheritance behavior can be turned on by declaring the annotation with the inheritable qualifier.

Most sub-commands and options of this command are identical to the SDL annotation declaration. There's only one subcommand that is allowed in the create annotation block:

create annotation annotation-name := value

Annotations can also have annotations. Set the annotation-name of the enclosing annotation to a specific value. See create annotation for details.

Example​

Declare an annotation extrainfo:

Copy
create abstract annotation extrainfo;

Alter abstract annotation​

Change the definition of an annotation.

alter abstract annotation name
[ "{" ] subcommand; [...] [ "}" ];

where subcommand is one of

  rename to newname
  create annotation annotation-name := value
  alter annotation annotation-name := value
  drop annotation annotation-name

Description​

alter abstract annotation changes the definition of an abstract annotation.

Parameters​

name

The name (optionally module-qualified) of the annotation to alter.

The following subcommands are allowed in the alter abstract annotation block:

rename to newname

Change the name of the annotation to newname.

alter annotation annotation-name := value

Annotations can also have annotations. Change annotation-name to a specific value. See alter annotation for details.

drop annotation annotation-name

Annotations can also have annotations. Remove annotation annotation-name. See drop annotation for details.

All the subcommands allowed in the create abstract annotation block are also valid subcommands for alter annotation block.

Example​

Rename an annotation:

Copy
alter abstract annotation extrainfo
  rename to extra_info;

Drop abstract annotation​

Drop a schema annotation.

[ with with-item [, ...] ]
drop abstract annotation name ;

Description​

The command drop abstract annotation removes an existing schema annotation from the database schema. Note that the inheritable qualifier is not necessary in this statement.

Example​

Drop the annotation extra_info:

Copy
drop abstract annotation extra_info;

Create annotation​

Define an annotation value for a given schema item.

create annotation annotation-name := value

Description​

The command create annotation defines an annotation for a schema item.

annotation-name refers to the name of a defined annotation, and value must be a constant EdgeQL expression evaluating into a string.

This statement can only be used as a subcommand in another DDL statement.

Example​

Create an object type User and set its title annotation to "User type".

Copy
create type User {
  create annotation title := "User type";
};

Alter annotation​

Alter an annotation value for a given schema item.

alter annotation annotation-name := value

Description​

The command alter annotation alters an annotation value on a schema item.

annotation-name refers to the name of a defined annotation, and value must be a constant EdgeQL expression evaluating into a string.

This statement can only be used as a subcommand in another DDL statement.

Example​

Alter an object type User and alter the value of its previously set title annotation to "User type".

Copy
alter type User {
  alter annotation title := "User type";
};

Drop annotation​

Remove an annotation from a given schema item.

drop annotation annotation-name ;

Description​

The command drop annotation removes an annotation value from a schema item.

annotaion_name refers to the name of a defined annotation. The annotation value does not have to exist on a schema item.

This statement can only be used as a subcommand in another DDL statement.

Example​

Drop the title annotation from the User object type:

Copy
alter type User {
  drop annotation title;
};