Quickstart

The Java SDK for SurrealDB makes it straightforward to connect to your instance and start querying data. This guide walks you through connecting, authenticating, and performing basic operations.

1. Install the SDK

Follow the installation guide to install the SDK as a dependency in your project. Once installed, import the SDK to start using it.

import com.surrealdb.Surreal;

2. Connect to SurrealDB

Use a try-with-resources block to create a connection, then call .useNs() and .useDb() to select a namespace and database, and .signin() to authenticate.

Supported connection protocols include:

• WebSocket (ws://, wss://) for long-lived stateful connections

• HTTP (http://, https://) for short-lived stateless connections

• Embedded (memory, surrealkv://) for in-process databases

import com.surrealdb.Surreal;
import com.surrealdb.signin.RootCredential;

try (Surreal db = new Surreal()) {
    db.connect("ws://localhost:8000");
    db.useNs("company_name").useDb("project_name");
    db.signin(new RootCredential("root", "root"));
}

The Surreal class implements AutoCloseable, so the connection is automatically closed at the end of the try-with-resources block.

3. Inserting data

To represent database records in your application, define POJO classes that match your table structure. A public no-argument constructor is required. Use a RecordId field named id to hold the record identifier.

import com.surrealdb.RecordId;

public class Person {
    public RecordId id;
    public String name;
    public int age;

    public Person() {
    }

    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }
}

Use .create() to insert records into a table. When passing a table name, the method returns a list of created records with generated IDs.

Person person = new Person("John", 32);
List<Person> created = db.create(Person.class, "persons", person);

To create a record with a specific ID, pass a RecordId instead. This returns the created record directly.

Person created = db.create(Person.class, new RecordId("persons", "john"), person);

4. Retrieving data

Selecting records

The .select() method retrieves all records from a table, or a single record by its RecordId.

Iterator<Person> persons = db.select(Person.class, "persons");

Optional<Person> john = db.select(Person.class, new RecordId("persons", "john"));

Running SurrealQL queries

For more advanced use cases, use the .queryBind() method to execute SurrealQL statements with bound parameters.

Response response = db.queryBind(
    "SELECT * FROM persons WHERE age > $min_age",
    Map.of("min_age", 25)
);

Value result = response.take(0);

5. Closing the connection

If you use a try-with-resources block as shown above, the connection is closed automatically. Otherwise, call .close() manually to release resources.

db.close();

What's next?

You have learned how to install the SDK, connect to SurrealDB, create records, and retrieve data. There is a lot more you can do with the SDK, including updating and deleting records, handling authentication, live queries, and transactions.