Value types
The Java SDK maps SurrealDB data types to native Java types where possible and provides custom classes for types that have no direct Java equivalent. You can work with results as untyped Value objects or pass a Class<T> to SDK methods for automatic deserialization into POJOs.
API References
| Class | Description |
|---|
Value | Represents any SurrealDB value |
RecordId | Represents a record identifier |
Geometry | Represents geometric data |
FileRef | Represents a file reference |
Datetime | Maps to java.time.ZonedDateTime |
Duration | Maps to java.time.Duration |
Table | Table name value, maps to String |
Range | Range value with start and end bounds |
Type mapping
SurrealDB types map to Java types as follows:
| SurrealDB Type | Java Type | Notes |
|---|
string | String | |
int | long | |
float | double | |
bool | boolean | |
null | null | |
none | Value.isNone() | Check via Value |
datetime | ZonedDateTime | java.time |
duration | Duration | java.time |
decimal | BigDecimal | java.math |
uuid | UUID | java.util |
bytes | byte[] | |
array | Array | SDK custom class |
object | Object | SDK custom class |
record | RecordId | SDK custom class |
geometry | Geometry | SDK custom class |
file | FileRef | SDK custom class |
table | String | Via Value.getTable() |
range | Value | Via Value.getRangeStart() / Value.getRangeEnd() |
Working with the Value class
Value is the untyped representation of any SurrealDB value. It provides type-checking methods and getters for extracting the underlying Java value.
Value value = response.take(0);
if (value.isLong()) {
long count = value.getLong();
}
if (value.isString()) {
String name = value.getString();
}
if (value.isArray()) {
Array items = value.getArray();
}
To convert a Value directly into a POJO, use .get(Class).
Person person = value.get(Person.class);
Using POJOs for type-safe access
Instead of working with raw Value objects, you can pass a Class<T> to most SDK methods to get automatic deserialization. POJOs need a public no-argument constructor, and their fields map directly to SurrealDB object keys.
public class Person {
public RecordId id;
public String name;
public int age;
public Person() {}
}
List<Person> people = db.create(Person.class, "person", newPerson);
Optional<Person> tobie = db.select(Person.class, new RecordId("person", "tobie"));
Constructing record identifiers
RecordId represents a SurrealDB record identifier consisting of a table name and an ID value. The ID can be a long, String, UUID, Array, or Object.
RecordId numericId = new RecordId("person", 1L);
RecordId stringId = new RecordId("person", "tobie");
RecordId uuidId = new RecordId("person", UUID.randomUUID());
Array compositeKey = new Array(2026, "Q1");
RecordId arrayId = new RecordId("report", compositeKey);
Object objectKey = new Object();
objectKey.put("region", "eu");
objectKey.put("year", 2026);
RecordId objectId = new RecordId("report", objectKey);
Iterating arrays and objects
The SDK’s Array class implements Iterable<Value>, and the Object class implements Iterable<Entry>. You can iterate over them using standard Java for-each loops.
Array items = value.getArray();
for (Value item : items) {
System.out.println(item.getString());
}
Object obj = value.getObject();
for (Entry entry : obj) {
System.out.println(entry.getKey() + ": " + entry.getValue());
}
When iterating from multiple threads, use synchronizedIterator() to get a thread-safe iterator.
Iterator<Value> safeIterator = items.synchronizedIterator();
Learn more
