TypeDB Driver API

TypeDB servers accept gRPC calls from TypeDB Clients. TypeDB Clients perform validation of queries, load balancing, and some other operations transparent for users.

To access all features of TypeDB and TypeDB Clients use the default interface provided by the Clients:

TypeDB Studio and TypeDB Console control sessions, transactions, and queries, as well as process the responses automatically to present the results (in GUI and CLI respectively) to user.

Both TypeDB Studio and TypeDB Console are built on the base of the Java Driver.

TypeDB Drivers provide greater flexibility and integration with popular programming languages/frameworks at the cost of the requirement to perform session, transaction, and data manipulation manually. To interact with a TypeDB Driver use TypeDB Driver API. There are slight differences between Driver APIs of different TypeDB Drivers, including syntax, but they are very similar to each other by design.

Driver API provides access to most functions of TypeDB Driver, and thus most functions of TypeDB. The following is a description of similar parts of APIs of different drivers. For more information on API methods, use the specific TypeDB Driver documentation.

API structure

Driver API is divided into two big sections:

  • Query section — classes and methods to connect to a TypeDB server, manage sessions and transactions, send different types of queries.

  • Response section — classes to store and provide processing methods for all concepts (types and instances) from a database.

Query

To send a query to a TypeDB server a TypeDB Driver needs to:

  • establish a server connection,

  • open a Session,

  • open a Transaction,

  • prepare TypeQL query string,

  • send the string as a proper type of query.

These operations are done using the special classes and methods provided by TypeDB Driver. See some examples of how to do that with different TypeDB Drivers: Connection, Sample application pages, or in the TypeDB Drivers documentation.

All queries are written in TypeQL, but for some languages there are libraries to build the TypeQL queries in a more native way. Like the TypeQL library for Java.

The exact syntax for these operations might be different in different languages. See the exact TypeDB Driver API documentation for more information: Java, Python, Node.js.

Response

In response to a query TypeDB server sends a response to the TypeDB Client. Client interprets the response and provides either a processed result (TypeDB Studio and TypeDB Console) or a special objects and methods to process the results (TypeDB Drivers). For every kind of query there is a predefined type of expected response and objects.

For more information on types (classes) of available objects and response types see the Response interpretation page.

For more information on types of response objects and their methods please see the API reference for the specific driver/language 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:

Local and remote methods

Any Driver API has two types of methods:

  • local

  • remote

The difference is that local concept methods do not require a call to the server, while calls to remote methods on the Driver API must make at least one full round-trip to a TypeDB server to fetch a result. The execution time will include at least the network latency between TypeDB Client and TypeDB server.

For example, to make 1,000 Remote Driver API calls and with latency (ping) from client to server being 10ms, we would spend a total of 10 seconds waiting for network round-trips. When dealing with large numbers of results, we recommend using a query to fetch all required information, rather than using the Remote methods of Driver API.

Queries always return local concepts. Local concepts must be explicitly converted to remote concepts to make remote methods available.

Local concepts

Local concept methods do not perform network operations. Local concepts are not bound to a transaction, so they can be safely used even after the transaction, session, or client has been closed; however, the information contained may go out of date if another transaction modifies the concepts on the server.

In the TypeDB Drivers documentation, the Local tag indicates that a method is available on both local and remote concepts. All other methods are only available on remote concepts.

Remote concepts

The remote concept methods allows a user to make simple requests to the TypeDB server to discover information connected to a specific concept, or modify a concept. All remote concept operations require a network call to a TypeDB server.

Remote concepts must be linked to a Transaction in order to make calls. When remote concepts are returned by a Transaction method or a Remote Driver API method, they will inherit the same Transaction as the transaction/concept the method was called on. When the Transaction is closed, the remote concept methods can no longer be used.

Some remote concept methods are update, insert, or delete operations, and will therefore fail if used on a concept that is linked to a read transaction.

Streamed query or method results (that were already being streamed at the time of remote method call) may or may not see updates made using the Driver API.

Converting local concepts to remote concepts

All local concepts have the method asRemote(tx), where the tx parameter is a Transaction to use for the remote concept version of this local concept, and the returned value is the remote concept. See the asRemote method documentation for more details: Java, Python, Node.js.