Getting started (Java)

In Java, you can access XTDB via a remote HTTP client, or in-process (e.g. for testing purposes).

Maven artifacts

The XTDB artifacts for each release are deployed to Maven Central:

pom.xml

<!-- currently only on the Maven Central 'open-source software repo hosting' (OSSRH) snapshots repo -->
<!-- releases will be deployed to Maven Central - at that point, this will no longer be required -->
<repositories>
    <repository>
        <id>ossrh-snapshots</id>
        <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

<dependencies>
    <!-- xtdb-api for the main public API, for both remote-client and in-process nodes -->
    <dependency>
        <groupId>com.xtdb</groupId>
        <artifactId>xtdb-api</artifactId>
        <version>2.0.0-SNAPSHOT</version>
    </dependency>

    <!-- xtdb-http-client-jvm for connecting to a remote server -->
    <dependency>
        <groupId>com.xtdb</groupId>
        <artifactId>xtdb-http-client-jvm</artifactId>
        <version>2.0.0-SNAPSHOT</version>
    </dependency>

    <!-- xtdb-core for running an in-process (test) node -->
    <dependency>
        <groupId>com.xtdb</groupId>
        <artifactId>xtdb-core</artifactId>
        <version>2.0.0-SNAPSHOT</version>
    </dependency>
</dependencies>

build.gradle.kts

repositories {
    maven {
        url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots")
    }
}

dependencies {
    // xtdb-api for the main public API, for both remote-client and in-process nodes
    implementation("com.xtdb:xtdb-api:2.0.0-SNAPSHOT")

    // xtdb-http-client-jvm for connecting to a remote server
    implementation("com.xtdb:xtdb-http-client-jvm:2.0.0-SNAPSHOT")

    // xtdb-core for running an in-process (test) node
    implementation("com.xtdb:xtdb-http-core:2.0.0-SNAPSHOT")
}

Connecting through HTTP

1. Firstly, to run the XTDB server, check out the general getting started guide.

2. Then, add the thin client Maven coordinates to your dependency manager of choice.

3. You can then open up an XTDB client by running:

   import java.net.URL;
   import xtdb.api.XtdbClient;
   
   try (var client = XtdbClient.openClient(new URL("http://localhost:3000"))) {
   
       // ...
   
   }

From here, check out the IXtdb API docs to submit data and run queries.

In process

If you’re running a JVM, you can also use XTDB directly, in-process. In-process XTDB is particularly useful for testing and interactive development - you can start an in-memory node quickly and with little hassle, which makes it a great tool for unit tests and REPL experimentation.

1. First, ensure you are running JDK 17+ and then add the xtdb-core Maven coordinates to your dependency manager.

2. You’ll also need to add the following JVM arguments to run Apache Arrow:

   • --add-opens=java.base/java.nio=ALL-UNNAMED

   • -Dio.netty.tryReflectionSetAccessible=true

3. Open up an in-process node using Xtdb:

   import xtdb.api.Xtdb;
   
   try(var xtdb = Xtdb.openNode()) {
       // ...
   }

This node uses exactly the same API as the thin client - so, again, from here, check out the IXtdb API docs to submit data and run queries.