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.
