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

Type mapping

SurrealDB types map to Java types as follows:

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

• Value API reference for complete Value class documentation

• RecordId API reference for record identifier details

• Geometry API reference for geometric data types

• FileRef API reference for file references

• Datetime API reference for datetime handling

• Duration API reference for duration handling

• Table API reference for table name values

• Range API reference for range values

• Data manipulation for using types with CRUD operations

• SurrealQL data model for the full list of SurrealDB data types