TypeDB Fundamentals Lecture Series: from Nov 16 to Jan 9

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


Fetch query

Stream/Iterator of JSON


Get query

Stream/Iterator of ConceptMap


Get query with aggregation

Promise of Value


Get query with grouping

Stream/Iterator of ConceptMapGroup


Get query with grouping and aggregation

Stream/Iterator of ValueGroup


Insert query

Stream/Iterator of ConceptMap


Delete query

Promise (of empty response)


Update query

Stream/Iterator of ConceptMap



Promise (of empty response)



Promise (of empty response)



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.

Use Promise object’s method to wait and retrieve the Value object when it’s ready.

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 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 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.


It’s a container for a ConceptMap object with an owner.


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


Value object represents a value.


ValueGroup object has not only a Value object but also an owner.


Promise object represents an asynchronous query result to be able to get the value later when query execution completes.


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.

Provide Feedback