Get query
|
This documentation is not current - it is for TypeDB 2.x, which is no longer supported. View the documentation for TypeDB 3.x: |
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.
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
| # | 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:
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:
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:
-
permissionrelation ($pe) of$xand$yvariables. -
$xispersonentity that has an attribute$x-nwith the typefull-name. -
The value of
$x-nshould contain the substringKevin. -
The
$yis aaccesstype relation of$oa role of object and$actas action. -
$acthas an attribute$act-nwith the typename. -
$ohas an attribute$o-fpwith the valuepath.
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:
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.