Data Manipulation Language

Match

match <pattern> ... (<modifier> ...)

A match will find all answers in the knowledge graph that satisfy all of the given patterns. Any optional modifiers are applied to the answers to the match.

The answers to a match can be used with either a get, insert, delete or aggregate.

Pattern

A pattern describes a set of constraints that an answer must satisfy.

It is either a variable pattern, a conjunction or a disjunction:

  • An answer satisfies a variable pattern if the concept bound to the subject of the variable pattern satisfies all properties in the variable pattern. e.g. $x isa person satisfies an answer $x=c1, $y=c2 if the concept c1 satisfies the property isa person.

  • Conjunction: { <pattern> ... }; - An answer satisfies a conjunction if it satisfies all patterns within the conjunction. e.g. { ($x, $y); $x isa person; } satisfies an answer $x=c1, $y=c2 if the answer satisfies both ($x, $y) and $x isa person.

  • Disjunction: <pattern> or <pattern>; - An answer satisfies a disjunction if it satisfies any pattern within the disjunction. e.g. { ($x, $y); } or { $x isa person; } satisfies an answer $x=c1, $y=c2 if the answer satisfies either ($x, $y) or $x isa person.

Within the patterns, the following properties are supported:

isa

$x isa $A is satisfied if $x is indirectly an instance of the type $A.

isa!

$x isa! $A is satisfied if $x is directly an instance of the type $A.

relationship

$r ($A1: $x1, ..., $An: $xn) is satisfied if $r is a relation where for each $Ai: $xi, $xi is a role-player in $r indirectly playing the role $Ai.

Additionally, for all pairs $Ai: $xi and $Aj: $xj where i != j, $xi and $xj must be different, or directly playing different roles in the relationship $r.

The variable representing the role can optionally be omitted. If it is omitted, then the first variable is implicitly bound to the label role.

has (data)

$x has <identifier> $y via $r is satisfied if $x is a thing related to an attribute $y of attribute type <identifier>, where $r represents the relationship between them.

The via $r is optional. Additionally, a predicate can be used instead of a variable:

$x has <identifier> <predicate>;

which is equivalent to:

$x has <identifier> $_;
$_ val <predicate>;

has is syntactic sugar for a particular kind of relationship.

It is equivalent to the following:

$r ($x, $y);
$y isa <identifier>;

val

$x val <predicate> is satisfied if $x is an attribute with a value satisfying the <predicate>.

id

$x id <identifier> is satisfied if $x has the ID <identifier>.

!=

$x != $y is satisfied if $x is not the same concept as $y.

label

$A label <identifier> is satisfied if $A is a schema concept with the label <identifier>.

sub

$A sub $B is satisfied if $A is a schema concept that is indirectly a sub-concept of a schema concept $B.

relates

$A relates $B is satisfied if $A is a relationship type that directly relates a role $B.

plays

$A plays $B is satisfied if $A is a type that indirectly plays a role $B.

has (type)

$A has <identifier> is satisfied if $A is a type whose instances can have instances of attribute type <identifier>.

has is syntactic sugar for a particular kind of relationship.

It is equivalent to the following:

$_R sub relationship, relates $_O, relates $_V;
$_O sub role;
$_V sub role;

$A plays $_O;
<identifier> plays $_V;

$_O != $_V;

key

$A has <identifier> is satisfied if $A is a type whose instances must have keys of attribute type <identifier>.

key is syntactic sugar for a particular kind of relationship.

It is equivalent to the following:

$_R sub relationship, relates $_O, relates $_V;
$_O sub role;
$_V sub role;

$A plays<<required>> $_O;
<identifier> plays $_V;

$_O != $_V;

(note that plays<<required>> is not valid syntax, but indicates that instances of the type must play the required role exactly once).

datatype

$A dataype <datatype> is satisfied if $A is an attribute type with the given datatype.

regex

$A regex <regex> is satisfied if $A is an attribute type with the given regex constraint.

is-abstract

$A is-abstract; is satisfied if $A is an abstract type.

Predicate

The following predicates can be applied to attributes:

  • =, !=, >, >=, <, <= - satisfied if the attribute’s values satisfy the comparison. These operators can also take a literal value.
  • contains <string> - satisfied if <string> is a substring of the attribute’s value.
  • /<regex>/ - satisfied if the attribute’s value matches the <regex>.

Modifier

There are several modifiers to change the answers of the match:

  • limit <n> - limit to only the first <n> answers.
  • offset <n> - skip the first <n> answers.
  • order by <variable> (asc | desc) - order the answers by the values of the concepts bound to the variable in ascending or descending order (ascending by default).

Modifiers are applied in order from left to right. For example, this means that order by $n; limit 100; will find the 100 answers with globally minimal $n, whereas limit 100; order by $n; will locally order the first 100 answers to the query.

Get Query

<match> get (<variable>, ...) ;

The get query will project each answer over the provided variables. If no variables are provided, then the answers are projected over all variables mentioned in the pattern.

Insert Query

(<match>) insert <variable pattern> ...

The insert query will insert the given variable patterns into the knowledge graph and return an answer with variables bound to concepts mentioned in the variable patterns.

If a match is provided, then the insert query will operate for every answer of the match, projected over the variables present in the insert query variable patterns and return one answer for each projected match answer.

Within the variable patterns, the following properties are supported:

isa

$x isa $A creates a new direct instance of the type $A and binds it to $x.

isa!

$x isa! $A creates a new direct instance of the type $A and binds it to $x.

relationship

$r ($A1: $x1, ..., $An, $xn) will, for each $Ai: $xi, add a new role-player $xi to the relationship $r directly playing the role $Ai.

has (data)

$x has <identifier> $y via $r will relate the attribute $y of attribute type <identifier> to $x, binding the relationship to $r.

If <identifier> is a key for the direct type of $x, then the resulting relationship will be a key relationship.

The via $r is optional. Additionally, a literal value can be used instead of a variable:

$x has <identifier> <value>;

which is equivalent to:

$x has <identifier> $_;
$_ val <value>;

has is syntactic sugar for a particular kind of relationship.

If <identifier> is not a key for the direct type of $x, it is equivalent to:

$r (has-<identifier>-owner: $x, has-<identifier>-value: $y) isa has-<identifier>;
$y isa <identifier>;

Otherwise, it is equivalent to:

$r (key-<identifier>-owner: $x, key-<identifier>-value: $y) isa key-<identifier>;
$y isa <identifier>;

val

$x val <value>; specifies that the attribute $x should have value <value>.

id

$x id <identifier> will assign $x to an existing concept with the given ID. It is an error if no such concept exists.

label

$A label <identifier> will assign $A to an existing schema concept with the given label. It is an error if no such schema concept exists.

Delete Query

<match> delete (<variable>, ...) ;

For every answer from the match, the delete query will delete the concept bound to every variable listed. If no variables are provided, then every variable mentioned in the match is deleted.

Aggregate Query

<match> aggregate <aggregate> ;

An aggregate query applies the given aggregate to the answers of the match.

Aggregate

<identifier> (< variable or aggregate > ...)

An aggregate query is a match followed by the keyword aggregate and an aggregate.

An aggregate begins with an aggregate name followed by zero or more arguments. An argument may be either a variable or another aggregate.

Examples of aggregates are:

  • ask
    • Return whether there are any answers.
  • count
  • group <variable> (<aggregate>)
  • max <variable>
  • median <variable>
  • mean <variable>
  • min <variable>
  • std <variable>
  • sum <variable>
  • (<aggregate> as <identifier> , ...)
    • The “product” aggregate has a special syntax: a comma-separated sequence of named aggregates surrounded by brackets ( ). This aggregate will execute all comprising aggregates and put the results in a map, keyed by the given identifiers.
Tags: graql