Data manipulation
The Java SDK provides dedicated methods for common CRUD operations on records and tables. These methods offer a structured alternative to writing raw SurrealQL, with built-in type safety through Java generics and POJO deserialization.
API References
Defining model classes
Data manipulation methods can work with POJOs (Plain Old Java Objects) for type-safe access. Model classes need a public no-argument constructor and fields that map to SurrealDB object keys. Use a RecordId field named id to hold the record identifier.
public class Person {
public RecordId id;
public String name;
public int age;
public Person() {}
}
Creating records
The .create() method creates new records. When called with a table name, SurrealDB generates a random ID and returns a list. When called with a RecordId, the record is created with that specific ID and a single result is returned.
Person alice = new Person();
alice.name = "Alice";
alice.age = 30;
List<Value> created = db.create("person", alice);
Value tobie = db.create(new RecordId("person", "tobie"), alice);
List<Person> typed = db.create(Person.class, "person", alice);
Selecting records
The .select() method reads records from the database. When called with a table name, it returns an Iterator. When called with a RecordId, it returns an Optional.
Iterator<Value> all = db.select("person");
Optional<Value> one = db.select(new RecordId("person", "tobie"));
Iterator<Person> allTyped = db.select(Person.class, "person");
Optional<Person> oneTyped = db.select(Person.class, new RecordId("person", "tobie"));
Use selectSync() instead of select() when you need thread-safe iteration over the results.
Inserting records
The .insert() method inserts one or more records into a table using varargs. This is more efficient than calling .create() in a loop for bulk operations.
Person alice = new Person();
alice.name = "Alice";
alice.age = 30;
Person bob = new Person();
bob.name = "Bob";
bob.age = 25;
List<Value> inserted = db.insert("person", alice, bob);
Use .insertRelation() to insert graph edge records. See Creating graph relations for details.
Updating records
The .update() method modifies existing records. You specify the update strategy using the UpType enum:
| UpType | Behavior |
|---|
UpType.CONTENT | Replaces the entire record with the new content |
UpType.MERGE | Merges new fields into the existing record |
UpType.PATCH | Applies a JSON Patch to the record |
Person updated = new Person();
updated.name = "Alice Smith";
updated.age = 31;
db.update(new RecordId("person", "alice"), UpType.CONTENT, updated);
db.update(new RecordId("person", "alice"), UpType.MERGE, Map.of("age", 31));
db.update("person", UpType.MERGE, Map.of("active", true));
Person result = db.update(
Person.class, new RecordId("person", "alice"), UpType.CONTENT, updated
);
Upserting records
The .upsert() method works like .update() but creates the record if it does not already exist. It accepts the same UpType strategies.
Person person = new Person();
person.name = "Charlie";
person.age = 28;
db.upsert(new RecordId("person", "charlie"), UpType.CONTENT, person);
Deleting records
The .delete() method removes records from the database. You can delete a single record by RecordId, multiple records by passing several RecordId values, a range of records with RecordIdRange, or all records in a table by passing the table name.
db.delete(new RecordId("person", "tobie"));
db.delete(new RecordId("person", "alice"), new RecordId("person", "bob"));
db.delete(new RecordIdRange("person", Id.from("a"), Id.from("f")));
db.delete("person");
Creating graph relations
The .relate() method creates edges between records in SurrealDB’s graph model. You specify the source record, the edge table, and the target record. Optionally, you can attach content to the edge.
db.relate(
new RecordId("person", "tobie"),
"likes",
new RecordId("post", 1)
);
db.relate(
new RecordId("person", "tobie"),
"likes",
new RecordId("post", 1),
Map.of("timestamp", "2026-02-27T12:00:00Z")
);
You can also use .insertRelation() to insert relation records with in and out fields, similar to how .insert() works for regular records.
public class Likes extends InsertRelation {
public String timestamp;
public Likes() {}
}
Likes like = new Likes();
like.in = new RecordId("person", "tobie");
like.out = new RecordId("post", 1);
like.timestamp = "2026-02-27T12:00:00Z";
db.insertRelation(Likes.class, "likes", like);
Learn more
