• Installation
• Quickstart
• API Reference
• Client
• Session
• Options
• Transaction
• TypeQL
• QueryManager
• Answer
• QueryFuture
• Version Compatibility

Installation

Prerequisites

To use this client, you need a compatible version of TypeDB Server running. Please see the Compatibility Table to check what version do you need, depending on the TypeDB server version being used.

Add a repository with TypeDB Java client to Maven

Add the code below to the pom.xml file in your Maven project.

<repositories>
    <repository>
        <id>repo.vaticle.com</id>
        <url>https://repo.vaticle.com/repository/maven/</url>
    </repository>
</repositories>
<dependencies>
<dependency>
    &lt;groupId&gt;com.vaticle.typedb&lt;/groupId&gt;
    &lt;artifactId&gt;typedb-client&lt;/artifactId&gt;
    <version>{version}</version>
</dependency>
</dependencies>

If you want to depend on snapshot versions of Client Java, by referring to the GitHub commit sha, you can add our snapshot repository to your list of Maven repositories.

<repositories>
    <repository>
        <id>repo.vaticle.com.snapshot</id>
        <name>repo.vaticle.comai</name>
        <url>https://repo.vaticle.com/repository/maven-snapshot/</url>
    </repository>
</repositories>

(Optional) Add logging config

By default, Client Java uses Logback to print errors and debugging info to standard output. As it is quite verbose, use the following steps to set the minimum log level to ERROR:

1. Create a file in the resources path (src/main/resources by default in a Maven project) named logback.xml.
2. Copy the following document into the logback.xml:

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="ERROR">
        <appender-ref ref="STDOUT"/>
    </root>

</configuration>

Resources

• Client Java on GitHub
• Releases
• Examples

Quickstart

First make sure, the TypeDB Server is running.

Import com.vaticle.typedb.client.TypeDB, instantiate a TypeDB Core client and open a session to a database.

package com.vaticle.doc.examples;


import com.vaticle.typedb.client.api.TypeDBClient;
import com.vaticle.typedb.client.api.TypeDBSession;
import com.vaticle.typedb.client.TypeDB;

public class TypeDBQuickstartA {
    public static void main(String[] args) {
        TypeDBClient client = TypeDB.coreClient("localhost:1729");
        // client is open
        TypeDBSession session = client.session("social_network", TypeDBSession.Type.DATA);
        // session is open
        session.close();
        // session is closed
        client.close();
        // client is closed
    }
}

Create transactions to use for reading and writing data.

package com.vaticle.doc.examples;

import com.vaticle.typedb.client.api.TypeDBClient;
import com.vaticle.typedb.client.api.TypeDBSession;
import com.vaticle.typedb.client.api.TypeDBTransaction;
import com.vaticle.typedb.client.TypeDB;

public class TypeDBQuickstartB {
    public static void main(String[] args) {
        TypeDBClient client = TypeDB.coreClient("localhost:1729");

        try (TypeDBSession session = client.session("social_network", TypeDBSession.Type.DATA)) {
            // creating a write transaction
            TypeDBTransaction writeTransaction = session.transaction(TypeDBTransaction.Type.WRITE);
            // write transaction is open
            // write transaction must always be committed (closed)
            writeTransaction.commit();

            // creating a read transaction
            TypeDBTransaction readTransaction = session.transaction(TypeDBTransaction.Type.READ);
            // read transaction is open
            // read transaction must always be closed
            readTransaction.close();
        }

        client.close();
    }
}

Running basic retrieval and insertion queries.

package com.vaticle.doc.examples;


import com.vaticle.typedb.client.api.TypeDBClient;
import com.vaticle.typedb.client.api.TypeDBSession;
import com.vaticle.typedb.client.api.TypeDBTransaction;
import com.vaticle.typedb.client.TypeDB;
import com.vaticle.typeql.lang.TypeQL;

import static com.vaticle.typeql.lang.TypeQL.*;

import com.vaticle.typeql.lang.query.TypeQLMatch;
import com.vaticle.typeql.lang.query.TypeQLInsert;
import com.vaticle.typedb.client.api.answer.ConceptMap;

import java.util.List;
import java.util.stream.Stream;
import java.util.stream.Collectors;

public class TypeDBQuickstartC {
    public static void main(String[] args) {
        TypeDBClient client = TypeDB.coreClient("localhost:1729");

        try (TypeDBSession session = client.session("social_network", TypeDBSession.Type.DATA)) {

            try (TypeDBTransaction writeTransaction = session.transaction(TypeDBTransaction.Type.WRITE)) {
                // Insert a person using a WRITE transaction
                TypeQLInsert insertQuery = TypeQL.insert(var("x").isa("person").has("email", "x@email.com"));
                List<ConceptMap> insertedId = writeTransaction.query().insert(insertQuery).collect(Collectors.toList());
                System.out.println("Inserted a person with ID: " + insertedId.get(0).get("x").asThing().getIID());
                // to persist changes, a write transaction must always be committed (closed)
                writeTransaction.commit();
            }

            try (TypeDBTransaction readTransaction = session.transaction(TypeDBTransaction.Type.READ)) {
                // Read the person using a READ only transaction
                TypeQLMatch.Limited getQuery = TypeQL.match(var("p").isa("person")).get("p").limit(10);
                Stream<ConceptMap> answers = readTransaction.query().match(getQuery);
                answers.forEach(answer -> System.out.println(answer.get("p").asThing().getIID()));
            }
        }

        client.close();
    }
}

Check out the Concept API to learn about the available methods on the concepts retrieved as the answers to queries.

To view examples of running various TypeQL queries using the Java client, head over to their dedicated documentation pages as listed below.

• Insert
• Get
• Delete
• Update
• Aggregate

API Reference

TypeDB.coreClient(String address, int parallelisation);

TypeDB.clusterClient(Set addresses, TypeDBCredential credential, int parallelisation);

Client

client.session(String database, Session.Type sessionType, TypeDBOptions options);

client.databases().all();

client.databases().contains(String database);

client.databases().create(String database);

client.databases().get(String database);

client.databases().get(String database).delete();

client.users().all();

client.users().contains(String user);

client.users().create(String user);

client.users().get(String user);

client.users().delete(String username);

client.users().passwordSet(String username, String password);

client.close();

Session

session.transaction(Transaction.Type transactionType, TypeDBOptions options);

session.isOpen();

session.type();

session.database();

session.close();

Options

The transaction query options object TypeDBOptions can be used to override the default server behaviour query processing. Use TypeDBOptions.core() to create a new TypeDB Core options object, or TypeDBOptions.cluster() for TypeDB Cluster.

The options are:

• infer: whether to enable inference for the provided query (only settable at transaction level and above, and only affects read transactions) (default: false)
• explain: whether to enable explanations for the provided query (only affects read transactions) (default: false)
• parallel: whether the server should use parallel or single-threaded execution (default: true)
• prefetchSize: a guideline number of answers that the server should send before the client issues a fresh request (default: 50)
• traceInference: if enabled, outputs reasoning tracing graphs in the logging directory. Should be used with parallel = false. (default: false)
• prefetch: if enabled, the first batch of answers is streamed to the client even without an explicit request for it (default: true if query type is match, otherwise false)
• sessionIdleTimeoutMillis: this timeout allows the server to close sessions if a client terminates or becomes unresponsive (default: 30_000)
• transactionTimeoutMillis: this timeout will automatically kill transactions, preventing memory leaks in unclosed transactions (default: 300_000)
• schemaLockAcquireTimeoutMillis: how long the client should wait if opening a session or transaction is blocked by a schema write lock (default: 10_000)

TypeDBClusterOptions has an additional option:

• readAnyReplica: enables reading data from any replica, potentially boosting read throughput (default: false)

options.setInfer(boolean enabled)

options.setExplain(boolean enabled)

options.setParallel(boolean parallel)

options.setPrefetchSize(int size)

options.setTraceInference(boolean traceInference)

options.setPrefetch(boolean prefetch)

options.setSessionIdleTimeoutMillis(int timeout)

options.setTransactionTimeoutMillis(int timeout)

options.setSchemaLockAcquireTimeoutMillis(int timeout)

clusterOptions.setReadAnyReplica(bool readAnyReplica)

Transaction

transaction.type();

transaction.isOpen();

transaction.concepts();

transaction.logic();

transaction.query();

transaction.commit();

transaction.rollback();

transaction.close();

TypeQL

TypeQL, the query language for TypeDB, is written in Java and its API can be used to programmatically construct TypeQL queries.

To use TypeQL, we first add it as a dependency to our pom.xml.

<repositories>
    <repository>
        <id>repo.vaticle.com</id>
        <url>https://repo.vaticle.com/repository/maven/</url>
    </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>com.vaticle.typeql</groupId>
        <artifactId>typeql-lang</artifactId>
        <version>{version}</version>
    </dependency>
</dependencies>

The latest version of typeql-lang can be found in the public Maven repository.

The we import TypeQL.

import com.vaticle.typeql.lang.TypeQL;

We are now ready to construct TypeQL queries, using the methods available on the TypeQL class. Check out the following pages to learn, by example, how the TypeQL API allows construction of various TypeQL queries:

• Expressive patterns
• Retrieval queries
• Insertion queries
• Deletion queries
• Aggregation queries

QueryManager

transaction.query().match(TypeQLMatch query, TypeDBOptions options);

transaction.query().match(TypeQLMatch.Aggregate query, TypeDBOptions options);

transaction.query().match(TypeQLMatch.Group query, TypeDBOptions options);

transaction.query().match(TypeQLMatch.Group.Aggregate query, TypeDBOptions options);

transaction.query().insert(TypeQLInsert query, TypeDBOptions options);

transaction.query().delete(TypeQLDelete query, TypeDBOptions options);

transaction.query().update(TypeQLUpdate query, TypeDBOptions options);

transaction.query().explain(ConceptMap.Explainable explainable, TypeDBOptions options);

transaction.query().define(TypeQLDefine query, TypeDBOptions options);

transaction.query().undefine(TypeQLUndefine query, TypeDBOptions options);

Answer

The type of answers returned by execution of a query depends on the type of query executed. The table below illustrates the answer types mapped to query types.

conceptMap.map();

conceptMap.concepts();

conceptMap.get(String var)

conceptMap.explainables()

numeric.asLong();

numeric.asDouble();

numeric.asNumber();

numeric.isLong();

numeric.isDouble();

conceptMapGroup.isNaN();

conceptMapGroup.owner();

conceptMapGroup.conceptMaps();

numericGroup.owner();

numericGroup.numeric();

conceptMap.explainables().relation(String variable);

conceptMap.explainables().attribute(String variable);

conceptMap.explainables().ownership(String ownerVar, String attributeVar);

conceptMap.explainables().relations();

conceptMap.explainables().attributes();

conceptMap.explainables().ownerships();

explainable.conjunction()

explainable.id()

explanation.rule();

explanation.conclusion()

explanation.condition()

explanation.variableMapping()

QueryFuture

Transaction queries that return single answers or empty responses are executed asynchronously on the server. To wait for a query to finish execution, and return its result if there is one, use the ‘get()’ function.

future.get()

future.map(function)

Version Compatibility