Java | SDK | API Reference

API Reference

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)

Parameter	Type	Description
`username` required	`String`	The root username.
`password` required	`String`	The root password.

Methods

Method	Returns	Description
`.getUsername()`	`String`	The root username
`.getPassword()`	`String`	The 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)

Parameter	Type	Description
`username` required	`String`	The namespace username.
`password` required	`String`	The namespace password.
`namespace` required	`String`	The namespace to authenticate against.

Additional Method

Method	Returns	Description
`.getNamespace()`	`String`	The 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)

Parameter	Type	Description
`username` required	`String`	The database username.
`password` required	`String`	The database password.
`namespace` required	`String`	The namespace containing the database.
`database` required	`String`	The database to authenticate against.

Additional Method

Method	Returns	Description
`.getDatabase()`	`String`	The 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)

Parameter	Type	Description
`namespace` optional	`String`	The namespace. Omit to use the session namespace.
`database` optional	`String`	The database. Omit to use the session database.
`access` required	`String`	The access method name.
`params` required	`Object`	Additional fields required by the access definition.

Methods

Method	Returns	Description
`.getNamespace()`	`String`	The target namespace
`.getDatabase()`	`String`	The target database
`.getAccess()`	`String`	The access method name
`.getParams()`	`Object`	The 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)

Parameter	Type	Description
`token` required	`String`	A valid JWT token string.

Method

Method	Returns	Description
`.getToken()`	`String`	The 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)

Parameter	Type	Description
`access` required	`String`	The access token (JWT).
`refresh` optional	`String`	The refresh token. May be `null`.
`token` required	`String`	A single token string (legacy constructor).

Methods

Method	Returns	Description
`.getAccess()`	`String`	The access token (JWT)
`.getRefresh()`	`String`	The refresh token (may be `null`)
`.getToken()`	`String`	The 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.

Value	Description
`CONTENT`	Replaces the entire record content
`MERGE`	Merges fields with the existing record
`PATCH`	Applies 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

Field	Type	Description
`id`	`RecordId`	The relation record ID
`in`	`RecordId`	The source record
`out`	`RecordId`	The 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

Field	Type	Description
`id`	`Id`	The relation ID
`in`	`RecordId`	The source record
`out`	`RecordId`	The 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

Method	Returns	Description
`.getNamespace()`	`String`	The namespace
`.getDatabase()`	`String`	The database

On this page

Was this page helpful?

What did you like?

What went wrong?