Match stage

A match stage performs pattern-based data retrieval and filtering. It takes input data assigned variables and verifies that this data satisfies the patterns in the body of the stage, while producing new results for any additional variables that the pattern

Syntax

match <pattern>

where <pattern> denotes a valid pattern.

Behavior

  • If a query pipeline start with a match clause, then the first match stage is given the empty row {} as its only input.

  • For each input row, the match stage outputs all combinations of data for its output variables (i.e., those variables that have not already been bound in earlier stages, and which are not internal to the stage).

  • It passes each output together with its inputs as a combined row to the next stage.

For example, if a match stage is given 2 input rows,

{ $x=a, $y=b }
{ $x=a, $y=c }

and for each input produces 2 outputs { $z=d } and { $z=e }, then the stage will pass 4 output rows to the next stage:

{ $x=a, $y=b, $z=e }
{ $x=a, $y=b, $z=d }
{ $x=a, $y=c, $z=e }
{ $x=a, $y=c, $z=d }

It may be the case that a match case does not produce any new outputs, but only filters down the inputs it is given by additional patterns. In this sense, match stages can be used both for retrieving new data and filtering down data as part of a pipeline.

Execution

Statements in the body pattern of match stage can be given in any order, and will not affect execution of the stage; the best order in which data will be retrieved from the database is determined by TypeDB’s query optimizer.

Validation

If no valid combinations of types can be inferred for the variables in body pattern of the stage the query will be rejected.

Examples

  1. Retrieve usernames of user who have more than 400 friends:

    match
  $x isa user;
  friendship($x, $y);
reduce $y_count = count groupby $x;
match
  $y_count > 500;
  $x has username $name;
select $name;

  2. Retrieve users with no friends:

    match
  $x isa user;
  not { friendship($x, $y); };

  3. Find users that are either VIP, or are admins with access level > 9000, in which case we also want to retrieve their exact access level.

    match
  $x isa user;
  { $x isa VIP; } or { $x isa admin, has access-level $lvl; $lvl > 9000; };

  4. Find all attributes that are set for a specific user, return them together with their type;

    match
  $x isa user, has username "specific_user";
  $x has $type $value;
select $type, $value;