Officially out now: The TypeDB 3.0 Roadmap

Get query

A Get query retrieves concepts as stateful objects from a TypeDB database that you can further process with the driver API methods. For a practical guide on how to send a Get query to TypeDB, see the Get query page of the TypeDB Manual. For response processing examples, see the data objects and schema objects pages.

Syntax

A Get query consists of a match and a get clauses:

match <pattern>
get [<variable> [, <variable>]];

Behavior

A Get query retrieves concepts from a database.

A match clause is used to match data by a pattern, while a get clause is used to filter the returned variables.

A Get query projects concepts matched from a database to language-specific programmatic stateful objects that can be used via driver API methods. The output of a Get query is a lazy stream/iterator of ConceptMap objects, unless it’s used with aggregation, grouping, or both. See the Response format section below.

You can use sorting and pagination with a Get query.

Get queries can use rule-based inference.

Match clause

A match clause in a Get query matches existing concepts in a database to retrieve them as objects. You can use a declarative and composable TypeQL pattern in a match clause and TypeDB will find data that matches specified pattern.

A match clause is mandatory in a Get query.

For more information on patterns and statements used in a match clause, see the Patterns and Statements sections.

Get clause

A get clause is used in a Get query to select variables (concept variables and value variables) to include in the output. An empty get clause (get;) includes all variables, used in the preceding match clause.

Response format

Table 1. Response format
# Query Response format

1

Get query

Stream/Iterator of ConceptMap

2

Get query with aggregation

Promise of Value

3

Get query with grouping

Stream/Iterator of ConceptMapGroup

4

Get query with grouping and aggregation

Stream/Iterator of ValueGroup

A Get query returns solutions matched by the match clause and filtered by the get clause, optionally processed by modifiers. A get clause returns exactly one ConceptMap for every solution matched by its preceding match clause. The results are in set semantics, meaning that there are no duplicates.

A ConceptMap object maps query variables to concept objects. To retrieve a concept object from a ConceptMap, use the driver API ConceptMap.get(variable) method, that takes input of variable’s label. Further processing of a concept object is done via methods of the driver API. For examples on how to work with schema and data concepts, see the Schema objects and Data objects pages.

Get concepts

For this example, use a database with the IAM schema and sample data loaded.

A simple Get query example:

Get example
match
$p isa person,
    has full-name "Kevin Morrison",
    has email $e;
get $e;

The above query uses only two variables: $p and $e. The full-name attribute is not bound to a variable in this query.

The example above matches person ($p) with ownership of the full-name attribute with a value of Kevin Morrison and the email attribute ($e) with any value. The get clause then filters the results to retrieve only the email ($e) attributes.

The response is a stream/iterator of ConceptMap. Every ConceptMap bounds the variable $e to an attribute of the email type, that matches the pattern.

Get with modifiers

For this example, use a database with the IAM schema and sample data loaded.

For the next example, let’s try a bit more complex pattern and some modifiers:

Complex Get query example
match
$pe ($x, $y) isa permission;
$x isa person, has full-name $x-n;
$x-n contains "Kevin";
$y (object: $o, action: $act) isa access;
$act has name $act-n;
$o has path $o-fp;
get $x-n, $act-n, $o-fp;
sort $o-fp;
group $o-fp;
count;

The example above uses a match clause to find data that matches the following conditions:

  1. permission relation ($pe) of $x and $y variables.

  2. $x is person entity that has an attribute $x-n with the type full-name.

  3. The value of $x-n should contain the substring Kevin.

  4. The $y is a access type relation of $o a role of object and $act as action.

  5. $act has an attribute $act-n with the type name.

  6. $o has an attribute $o-fp with the value path.

The get clause then filters the matched answers from the match clause to get only the concepts for the $x-n, $act-n, $o-fp variables.

The results are sorted and grouped by the $o-fp and aggregated with the count function.

The response is the number of results for every $o-fp: number of pairs $x-n and $act-n.

Effects of filtering

For this example, use a database with the IAM schema and sample data loaded.

A Get query can return fewer results, than matched by its match clause, due to filtering with a get clause or using modifiers.

Get clause filtering

For this example, use a database with the IAM schema and sample data loaded.

Filtering variables with a get clause can reduce the number of results. Due to set semantics, some results might lose their uniqueness and made redundant. Let’s see the following example with matching entities of the person type that have a full-name attribute:

Get clause filter example
match
$p isa person, has full-name $n;
get $n;

The match clause returns pairs of person and its full-name. The get clause then returns only the full-name attributes.

If multiple entities have the same attribute, that is represented in a database as ownership of the very same single attribute. Since we filter the results to have only the $n variable, the results include such a name, but only once. Regardless of how many entities $p own it. To prevent such deduplication, in this example, you can extend the results to include the $p variable into every result, since every entity is unique. The results then will include pairs of $p and $n.

Using modifiers

Applying modifiers can have a drastic effect on the format and number of results returned by a Get query. See the table above for output formats depending on the usage of grouping and aggregation.

Usage of the limit modifier directly sets a limitation for the number of results.

Combination of Get clause filtering and Sorting can produce somewhat unpredictable results, if sorting is done by a variable, that is not included in the get clause.

Learn more

Learn more about query patterns in TypeDB Academy.

See how to send a Get query to TypeDB.

See how to manipulate Schema stateful objects with driver API.

See how to manipulate Data stateful objects with driver API.