• Start

Languages

/

Java

/

API Reference

/

Java Types

Java types

The Java SDK provides credential classes, enums, and helper types for authentication and data operations.

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

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

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

Implements Signin. Authenticates as a root user.

Constructor
RootCredential(String username, String password)

Parameter

Type

Description

usernameString

The root username.

passwordString

The root password.

MethodReturnsDescription
.getUsername()StringThe root username
.getPassword()StringThe root password
Example
db.signin(new RootCredential("root", "root"));

Extends RootCredential. Authenticates as a namespace user.

Constructor
NamespaceCredential(String username, String password, String namespace)

Parameter

Type

Description

usernameString

The namespace username.

passwordString

The namespace password.

namespaceString

The namespace to authenticate against.

MethodReturnsDescription
.getNamespace()StringThe target namespace
Example
db.signin(new NamespaceCredential("ns_user", "ns_pass", "surrealdb"));

Extends NamespaceCredential. Authenticates as a database user.

Constructor
DatabaseCredential(String username, String password, String namespace, String database)

Parameter

Type

Description

usernameString

The database username.

passwordString

The database password.

namespaceString

The namespace containing the database.

databaseString

The database to authenticate against.

MethodReturnsDescription
.getDatabase()StringThe target database
Example
db.signin(new DatabaseCredential("db_user", "db_pass", "surrealdb", "docs"));

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)

Parameter

Type

Description

namespaceString

The namespace. Omit to use the session namespace.

databaseString

The database. Omit to use the session database.

accessString

The access method name.

paramsObject

Additional fields required by the access definition.

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")
));

Implements Credential. Authenticates with an existing token.

Constructor
BearerCredential(String token)

Parameter

Type

Description

tokenString

A valid JWT token string.

MethodReturnsDescription
.getToken()StringThe bearer token
Example
db.signin(new BearerCredential("eyJhbGciOiJIUzI1NiIs..."));

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

Constructors
Token(String access, String refresh)
Token(String token)

Parameter

Type

Description

accessString

The access token (JWT).

refreshString

The refresh token. May be

null

.

tokenString

A single token string (legacy constructor).

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();

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);

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

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")
);

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

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);

Holds a namespace and database pair.

MethodReturnsDescription
.getNamespace()StringThe namespace
.getDatabase()StringThe database
  • Surreal — Connection and method reference

  • Authentication — Authentication concepts and patterns

  • Data manipulation — CRUD operation patterns

  • DEFINE USER — System user definition for root, namespace, and database credentials

  • DEFINE ACCESS — Access method definition for record-level authentication

Was this page helpful?