The official SurrealDB SDK for Java

     

     

surrealdb.java

The official SurrealDB SDK for Java.

Documentation

View the SDK documentation here.

Features

• A thread-safe native JAVA client for SurrealDB.
• Simple API: see docs.
• Support of 'memory' (embedded SurrealDB).
• Support of remote connection to SurrealDB.
• Mutable POJOs (Java 8+) and immutable record classes (JDK 16+) for create / select.
• All geometry types (Point, LineString, Polygon, their multi-variants, and GeometryCollection) for reading and writing.
• Supported on JAVA JDK 8, 11, 17, 21, 25.
• Supported architectures:
  • Linux (ARM) aarch64
  • Linux (INTEL) x86_64
  • Windows (INTEL) x86_64
  • MacOS (ARM) aarch64
  • MacOS (INTEL) x86_64
  • Android (Linux ARM) aarch64
  • Android (Linux INTEL) x86_64
• Zero dependencies

Minimum requirements

• Java 8

How to install

Stable release

Released to Maven Central.

Gradle:

ext {
    surrealdbVersion = "2.1.1"
}

dependencies {
    implementation "com.surrealdb:surrealdb:${surrealdbVersion}"
}

Maven:

<dependency>
    <groupId>com.surrealdb</groupId>
    <artifactId>surrealdb</artifactId>
    <version>2.1.1</version>
</dependency>

Snapshot release

Published to the Maven Central snapshots repository on every push to main. Use it to try out unreleased changes.

Gradle:

repositories {
    mavenCentral()
    maven {
        url = uri("https://central.sonatype.com/repository/maven-snapshots/")
        mavenContent { snapshotsOnly() }
    }
}

ext {
    surrealdbVersion = "2.1.2-SNAPSHOT"
}

dependencies {
    implementation "com.surrealdb:surrealdb:${surrealdbVersion}"
}

Maven:

<repositories>
    <repository>
        <id>central-snapshots</id>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        <releases><enabled>false</enabled></releases>
        <snapshots><enabled>true</enabled></snapshots>
    </repository>
</repositories>

<dependency>
    <groupId>com.surrealdb</groupId>
    <artifactId>surrealdb</artifactId>
    <version>2.1.2-SNAPSHOT</version>
</dependency>

Getting started

package org.example;

import com.surrealdb.Surreal;
import com.surrealdb.RecordId;

import java.util.Iterator;

public class Example {
    public static void main(String[] args) {
        try (final Surreal driver = new Surreal()) {
            // Connect to the instance
            driver.connect("memory");
            // namespace & database
            driver.useNs("test").useDb("test");
            // Create a person
            Person person = new Person("Founder & CEO", "Tobie", "Morgan Hitchcock", true);
            // Insert a record
            List<Person> tobie = driver.create(Person.class, "person", person);
            // Read records
            Iterator<Person> people = driver.select(Person.class, "person");
            // Print them out
            System.out.println("Tobie = " + tobie);
            System.out.println("people = " + people.next());
        }
    }

    static class Person {
        RecordId id;
        String title;
        String firstName;
        String lastName;
        boolean marketing;

        //  A default constructor is required
        public Person() {
        }

        public Person(String title, String firstName, String lastName, boolean marketing) {
            this.title = title;
            this.firstName = firstName;
            this.lastName = lastName;
            this.marketing = marketing;
        }

        @Override
        public String toString() {
            return "Person{" +
                    "id='" + id + '\'' +
                    ", title='" + title + '\'' +
                    ", firstName='" + firstName + '\'' +
                    ", lastName='" + lastName + '\'' +
                    ", marketing=" + marketing +
                    '}';
        }
    }
}

Geometry

All GeoJSON-style geometry types are supported — Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection — for both reading and writing. Coordinates use java.awt.geom.Point2D.Double, where x is the longitude and y is the latitude.

import com.surrealdb.Geometry;
import com.surrealdb.Surreal;
import com.surrealdb.Value;

import java.awt.geom.Point2D;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

try (final Surreal driver = new Surreal()) {
    driver.connect("memory").useNs("test").useDb("test");

    // Build a geometry in Java and store it via a bound parameter
    Geometry route = Geometry.lineString(Arrays.asList(
            new Point2D.Double(-0.118, 51.51),
            new Point2D.Double(-0.121, 51.50)));
    Map<String, Object> params = new HashMap<>();
    params.put("route", route);
    driver.query("UPSERT path:1 SET route = $route", params);

    // Read it back
    Value value = driver.query("SELECT VALUE route FROM path:1").take(0).getArray().get(0);
    Geometry geom = value.getGeometry();
    System.out.println(geom.getType());        // LineString
    System.out.println(geom.getLineString());  // [Point2D.Double[...], Point2D.Double[...]]
}

Reports

• Javadoc
• Test summary
• Coverage report

Developing

On Linux/Mac:

cargo build
./gradlew -i test

On Windows:

cargo build
./gradlew.bat -i test

Planned Features

• Futures
• Killing live queries by ID

Open an issue for feature requests