Java Types

The SDK provides several supporting types for authentication, update operations, and relation modeling. These types are used as parameters to methods on the Surreal class.

Source: surrealdb.java

Authentication Types

Credential

Interface. Base type for all credentials passed to signin() and signup().

Signin

Interface. Extends Credential. Marker interface for sign-in credentials.

RootCredential

Implements Signin. Authenticates as a root user.

Constructor

RootCredential(String username, String password)
ParameterTypeDescription
username StringThe root username.
password StringThe root password.

Methods

MethodReturnsDescription
.getUsername()StringThe root username
.getPassword()StringThe root password

Example

db.signin(new RootCredential("root", "root"));

NamespaceCredential

Extends RootCredential. Authenticates as a namespace user.

Constructor

NamespaceCredential(String username, String password, String namespace)
ParameterTypeDescription
username StringThe namespace username.
password StringThe namespace password.
namespace StringThe namespace to authenticate against.

Additional Method

MethodReturnsDescription
.getNamespace()StringThe target namespace

Example

db.signin(new NamespaceCredential("ns_user", "ns_pass", "surrealdb"));

DatabaseCredential

Extends NamespaceCredential. Authenticates as a database user.

Constructor

DatabaseCredential(String username, String password, String namespace, String database)
ParameterTypeDescription
username StringThe database username.
password StringThe database password.
namespace StringThe namespace containing the database.
database StringThe database to authenticate against.

Additional Method

MethodReturnsDescription
.getDatabase()StringThe target database

Example

db.signin(new DatabaseCredential("db_user", "db_pass", "surrealdb", "docs"));

RecordCredential

Implements Credential. Authenticates as a record user via an access method defined with DEFINE ACCESS.

Constructors

RecordCredential(String namespace, String database, String access, Object params)
RecordCredential(String access, Object params)
ParameterTypeDescription
namespace StringThe namespace. Omit to use the session namespace.
database StringThe database. Omit to use the session database.
access StringThe access method name.
params ObjectAdditional fields required by the access definition.

Methods

MethodReturnsDescription
.getNamespace()StringThe target namespace
.getDatabase()StringThe target database
.getAccess()StringThe access method name
.getParams()ObjectThe additional parameters

Example

Token token = db.signup(new RecordCredential(
"surrealdb", "docs", "user_access",
Map.of("email", "user@example.com", "password", "s3cret")
));

BearerCredential

Implements Credential. Authenticates with an existing token.

Constructor

BearerCredential(String token)
ParameterTypeDescription
token StringA valid JWT token string.

Method

MethodReturnsDescription
.getToken()StringThe bearer token

Example

db.signin(new BearerCredential("eyJhbGciOiJIUzI1NiIs..."));

Token

Represents authentication tokens returned by signin() and signup().

Constructors

Token(String access, String refresh)
Token(String token)
ParameterTypeDescription
access StringThe access token (JWT).
refresh StringThe refresh token. May be null.
token StringA single token string (legacy constructor).

Methods

MethodReturnsDescription
.getAccess()StringThe access token (JWT)
.getRefresh()StringThe refresh token (may be null)
.getToken()StringThe access token

Example

Token token = db.signin(new RootCredential("root", "root"));
String jwt = token.getAccess();
String refresh = token.getRefresh();

Operation Types

UpType

Enum for update() and upsert() operation types.

ValueDescription
CONTENTReplaces the entire record content
MERGEMerges fields with the existing record
PATCHApplies partial changes

Example

db.update(Person.class, new RecordId("person", "alice"), UpType.MERGE, updates);

Relation Types

Relation

POJO base class for graph relations. Contains the standard relation fields. Used with relate().

Fields

FieldTypeDescription
idRecordIdThe relation record ID
inRecordIdThe source record
outRecordIdThe target record

Example

public class Likes extends Relation {
public String createdAt;
}

Likes like = db.relate(Likes.class,
new RecordId("person", "alice"),
"likes",
new RecordId("post", "post1")
);

InsertRelation

POJO for inserting relations. Uses Id instead of RecordId for the id field. Used with insertRelation().

Fields

FieldTypeDescription
idIdThe relation ID
inRecordIdThe source record
outRecordIdThe target record

Example

public class Likes extends InsertRelation {
public String createdAt;
}

Likes like = new Likes();
like.in = new RecordId("person", "alice");
like.out = new RecordId("post", "post1");
like.createdAt = "2025-01-01T00:00:00Z";

Likes result = db.insertRelation(Likes.class, "likes", like);

Utility Types

NsDb

Holds a namespace and database pair.

Methods

MethodReturnsDescription
.getNamespace()StringThe namespace
.getDatabase()StringThe database

See Also