Matching patterns
A match clause is used by all data queries to seek data and types in a TypeDB database based on a provided pattern.
It can be used only as a part of a data query
with another clause to specify how to use the matched data.
Syntax
A match clause starts with the match keyword, followed by the pattern that is to be matched:
match <pattern>Pattern composition
A pattern consists of one or multiple statements, combined by any combination of conjunctions, disjunctions, and negations.
A matching pattern can use any valid TypeQL statements,
except the rule definition statement.
Other clauses use limited subsets of statements, e.g.,
a pattern in an insert or delete clause can use only data-specific statements
and can reuse variables matched by a match clause.
Behavior
A match clause is used to find all existing concepts in a database that satisfy a pattern.
These concepts are called the matched results of that pattern.
Satisfaction of a pattern depends on the structure of the pattern:
-
In a conjunction of patterns, each pattern must hold true.
-
In a disjunction of patterns, at least one pattern must hold true.
-
In a negation of a pattern, the negated pattern must be false.
Note that the order of patterns in conjunctions or disjunctions is irrelevant.
Execution and results
A match clause finds a set of matched results.
Every matched result contains
-
an exact value for every value variable
-
an exact concept for every concept variable.
Matched results for a pattern are solution for that pattern, meaning when you substitute variables in a pattern with values and concepts from a solution, it becomes a true statement.
Note that a match clause is an intermediate step in the execution of queries and thus does not directly provide a response to the user.
Matching a specific concept
To match a specific concept, use statements to set enough constraints for a concept variable to distinguish the concept
from all others.
For example, to match an attribute of the full-name type with the value of Kevin Morrison,
you can use the following pattern in a match clause:
$name isa full-name;
$name == "Kevin Morrison";The above pattern consists of two simple statements that can be combined in a comma-separated composite statement that produces the same effect.
It may be easier to find a specific entity using its attributes, if there is the unique or key annotation set in the schema.
You can think of matching a pattern as solving a system of equations, where every single statement in a pattern is an equation. TypeDB solves the system and returns all its solutions, including permutations.
Matching with duplicates
The number of results found (and returned) can be zero (no solutions found), one, or multiple. Due to set semantics of results, there can be no duplicates.
Consider the following example:
$p isa person, has full-name $n;The above example contains a pattern for an instance of person type having a full-name attribute.
If there is a person with no full-name attributes in a database, then such a person will not be matched.
If there is a person with two full-name attributes, then such a person will be matched in two results: one for each
full-name.
|
A |
Matching with permutations
A match clause returns all possible solutions for the given pattern based on the data and schema of a database.
That includes all permutations of results between variables.
For example, let’s match two different variables to all entities of the person type:
$p1 isa person;
$p2 isa person;Given that we have a total of three entities of the person type in the database,
the result should be nine pairs of tto entities each (one per every matched variable).
See the table representation of the results below:
|
Person 1 |
Person 2 |
Person 3 |
Person 1 |
11 |
12 |
13 |
Person 2 |
21 |
22 |
23 |
Person 3 |
31 |
32 |
33 |