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


Get query

Stream/Iterator of ConceptMap


Get query with aggregation

Future of Numeric


Get query with grouping

Stream/Iterator of ConceptMapGroup


Get query with grouping and aggregation

Stream/Iterator of NumericGroup


Insert query

Stream/Iterator of ConceptMap


Delete query

Future (of empty response)


Update query

Stream/Iterator of ConceptMap



Future (of empty response)



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

Every iteration returns the result as a ConceptMap object.

Get query with aggregation

The get query with aggregation can only return a singular value (aggregated result). Hence, it returns a Future object of Numeric.

Use Future object’s get() method to wait and retrieve the Numeric 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 NumericGroup objects.

Every iteration should return the result as a NumericGroup object.

Use NumericGroup object to retrieve Numeric.

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 Future object of a void (empty response).

We can’t retrieve any useful data from the Future object for 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 please see the API & Drivers page and documentation for the Java, Python, and Node.js TypeDB Drivers respectively.


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.

TypeDB Driver API methods can be used to get a JSON out of Concept returned in a response.

The exact syntax differs for every language specific API:


Numeric object represents a numeric value.


NumericGroup object has not only a Numeric object but also an owner.


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