Response interpretation
TypeDB can return a response to a TypeQL query in different formats, depending on a type of query. The server response will be processed by a TypeDB Client. TypeDB Client provides classes and methods for different response types respectively. Please see the table below for mapping of response format to a type of query that has been sent.
| # | Query type | Response format |
|---|---|---|
1 |
Stream/Iterator of JSON |
|
2 |
Stream/Iterator of ConceptMap |
|
3 |
Get query with aggregation |
Promise of Value |
4 |
Get query with grouping |
Stream/Iterator of ConceptMapGroup |
5 |
Get query with grouping and aggregation |
Stream/Iterator of ValueGroup |
6 |
Stream/Iterator of ConceptMap |
|
7 |
Promise (of empty response) |
|
8 |
Stream/Iterator of ConceptMap |
|
9 |
Promise (of empty response) |
|
10 |
Promise (of empty response) |
|
11 |
Stream/Iterator of Explanation |
TypeDB Driver API methods can be used to process the objects returned: get values of attributes, get JSON representation of data, or even get other concepts from a database.
Expected results
See the table above for an overview of response formats. For more details see the Response formats section below.
Get query
The ordinary Get query (without aggregation or grouping) returns a stream/iterator of a ConceptMap objects.
Get query with aggregation
The get query with aggregation can only return a singular value (aggregated result). Hence, it returns a Promise object of Value.
Get query with grouping
The get query with grouping returns a stream/iterator of ConceptMapGroup objects.
Every iteration should return the result as a ConceptMapGroup object.
Use ConceptMapGroup object to retrieve ConceptMap.
Get query with grouping and aggregation
The get query with grouping and aggregation returns a stream/iterator of a ValueGroup objects.
Every iteration should return the result as a ValueGroup object.
Use ValueGroup object to retrieve Value.
Insert query
An insert query returns a stream/iterator of a ConceptMap objects.
Every iteration should return the result as a ConceptMap object.
Delete query
Delete query can only return a Promise object of a void (empty response).
We can’t retrieve any useful data from the Promise object of a delete query.
Update (match-delete-insert) query
Similar to an insert query.
Define query
Similar to a delete query.
Undefine query
Similar to a delete query.
Explain
Explain query returns a stream/iterator of an Explanation objects.
For more information on inference explanation please see the Inferring data page.
Response formats
TypeDB Studio and TypeDB Console process the responses automatically to present the results (in GUI and CLI respectively) to the user.
For TypeDB Drivers: the specific methods/calls used to interpret the response depend on the TypeDB Driver used.
The following is a very basic description of objects used to interpret the results from the TypeDB query response. For more information, see the TypeDB Driver pages for the Rust, Python, Java, and Node.js.
ConceptMap
ConceptMap is a special object, made for mapping of variables from a query to concepts in a database. Its methods provide a way to interact with the concepts.
Usually represents a single solution/answer from a stream of answers for a TypeDB query.
ConceptMapGroup
It’s a container for a ConceptMap object with an owner.
Concept
Object to represent a type or an instance of a type (data) from a database.
There are separate methods for every built-in type and for instances of every built-in type.
|
To get |
Promise
Promise object represents an asynchronous query result to be able to get the value later when query execution completes.
Explanation
Explanation is a special object returned as a response to an explain query.
These are used to explain data inference. To perform an
explain query use explainables and explainable objects.
Number of answers
If the query type can return multiple results (e.g., a Get query) then the result of such query type is a stream/iterator to iterate through all the results. Even if the actual query of such type returns one result or no results at all — it returns a stream/iterator with one or zero iterations respectively.
Query types that can return only a single answer or a void (an empty response) are executed fully asynchronous on the
server. To wait for a query to finish execution, and return its result if there is one, use the get() method of the
Promise object returned by the query.
Best practice
Asynchronous queries
Invoking a TypeQL query sends it to a TypeDB server, where it will be completed in the background. Local processing can take place while waiting for responses to be received. Take advantage of these asynchronous queries to mask network round-trip costs and increase throughput.
For example, if we are performing 10 get queries in a transaction, it’s best to send them all to the server before iterating over any of their answers.