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

Schema for the following examples 
#!test[schema, commit]
define
  entity content owns id;
  entity page sub content,
    owns page-id,
    owns name;
  entity profile sub page,
    owns username;
  entity user sub profile,
    owns phone,
    owns karma;

  attribute id value string;
  attribute page-id sub id;
  attribute username sub page-id;
  attribute name value string;
  attribute phone value string;
  attribute karma value double;
attribute start-date, value date;
relation friendship relates friend @card(0..2), owns start-date;
user plays friendship:friend;

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

    #!test[read]
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:

    #!test[read]
match
  $x isa user;
  not { friendship($x, $y); };

  3. Find users that are either VIP, or are admins with access level > 9000.

    #!test[schema, commit]
#{{
define
  attribute access-level, value integer;
  entity VIP sub user;
  entity admin sub user, owns access-level;
#}}
#!test[read]
match
  $x isa user;
  { $x isa VIP; } or { $x isa admin, has access-level > 9000; };

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

    #!test[read]
match
  $x isa user, has username "specific_user";
  $x has $type $value;
select $type, $value;