RelationalAI SDK for Java
This guide presents the main features of the RelationalAI SDK for Java, which is used to interact with RelationalAI’s Relational Knowledge Graph System (RKGS).

The rai-sdk-java
package is open source and is available in the GitHub repository:

It includes self-contained examples (opens in a new tab) of the main API functionality. Contributions and pull requests are welcome.
Note: This guide applies to rai-sdk-java
, the latest iteration of the the RelationalAI SDK for Java.
The relationalai-sdk
package is deprecated.
Requirements
You can check the rai-sdk-java (opens in a new tab) repository for the latest version requirements to interact with the RKGS using the RelationalAI SDK for Java.
Installation
The SDK has a single runtime dependency (jsoniter), a dependency for running the SDK examples (commons-cli), and several additional dependencies for running the unit and integration tests.
To build the SDK you need to first clone it from the GitHub repository:
git clone https://github.com/RelationalAI/rai-sdk-java
Next, you can build it using Maven. The SDK’s build life cycle is managed through the standard mvn
life cycle commands.
The following commands are issued within the rai-sdk-java
directory:
cd rai-sdk-java
This is how to compile the SDK:
mvn compile
This is how to run the various SDK tests:
mvn test
Note that the tests are run against the account configured in your SDK config file, as shown in the next section.
You can compile, package, run the tests, and then install the SDK like this:
mvn install
Note that mvn install
is required to build and run the examples.
You can also specify the -Dskiptests
parameter in nvm install
if you want to compile, package, and install without running any tests.
You can clean up your source tree using:
mvn clean
Using the RelationalAI SDK for Java as a Maven Dependency
In order to use rai-sdk-java
, you need to add a dependency to your project’s POM file:
<dependency>
<groupId>com.relationalai</groupId>
<artifactId>rai-sdk</artifactId>
<version>0.4.0-alpha</version>
</dependency>
You also need to point Maven to the SDK’s GitHub packages repository, found in the project’s POM file:
<repositories>
<repository>
<id>github</id>
<name>The RelationalAI SDK for Apache Maven</name>
<url>https://maven.pkg.github.com/RelationalAI/rai-sdk-java</url>
</repository>
</repositories>
The registry access is generally available through the GitHub API, which is user-password protected.
As a result, you need to add your GitHub credentials to $HOME/.m2/settings.xml
:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
...
<servers>
<server>
<id>github</id>
<username>GITHUB_USERNAME</username>
<password>GITHUB_ACCESS_TOKEN</password>
</server>
</servers>
...
</settings>
In this case, GITHUB_USERNAME
is your GitHub login name.
Similarly, GITHUB_ACCESS_TOKEN
is a GitHub-generated access token specifically assigned to you.
You can generate a new token from GitHub by going to GitHub > Settings > Developer Settings > Personal access tokens > Generate new token.
Your new token needs to have at least the read:packages
scope.
Configuration
The RelationalAI SDK for Java can access your RAI Server credentials using a configuration file. See SDK Configuration for more details.
The Java Config
class represents a configuration to connect to the RAI Server.
You can load the configuration with a Java application as follows:
import java.io.IOException;
import com.relationalai.Config;
public class MyJava {
public static void main(String[] args) {
try {
var cfg = Config.loadConfig("~/.rai/config", "default");
}
catch (IOException e) {
System.out.println("Error occured.");
}
}
}
To load a different configuration, you can replace "default"
with a different profile name.
Creating a Client
Most API operations use a client object that contains the necessary settings for making requests against the RelationalAI REST APIs.
To create a client using the default
profile in your ~/.rai/config
file, you can use:
import java.io.IOException;
import com.relationalai.Client;
import com.relationalai.Config;
public class MyJava {
public static void main(String[] args) {
try {
var cfg = Config.loadConfig("~/.rai/config", "default");
var client = new Client(cfg);
}
catch (IOException e) {
System.out.println("Error occured.");
}
}
}
You can test your configuration and client by listing the databases as follows:
import java.io.IOException;
import com.relationalai.Client;
import com.relationalai.Config;
import com.relationalai.Json;
public class MyJava {
public static void main(String[] args) {
try {
var cfg = Config.loadConfig("~/.rai/config", "default");
var client = new Client(cfg);
var rsp = client.listDatabases();
Json.print(rsp, 4);
}
catch (Exception e) {
System.out.println("Error occured.");
}
}
}
This should print a list with database info, assuming your keys have the corresponding permissions. See Listing Databases below.
The remaining code examples in this document assume that you have a valid client in the client
Java variable and that you have imported the necessary com.relationalai.*
packages, such as the ones in the previous examples.
For example:
import com.relationalai.Client;
import com.relationalai.Config;
import com.relationalai.Json;
...
Additionally, most of the Java API calls throw an HTTPError
, InterruptedException
or IOException
exception when there is an issue.
Therefore, you can typically wrap the API calls discussed here in a try ... catch
block similar to the ones above.
For example:
try {
...
var rsp = client.listDatabases();
}
catch (HTTPError e) {
// handle error and/or rethrow
}
Managing Users
A client with the right permissions can create, disable, and list the users under the account.
Creating a User
You can create a user using the createUser (opens in a new tab) member function of a client (opens in a new tab) object:
var user = client.createUser(email, roles);
Here, email
is a string, identifying the user, and roles
is a list of strings, each one representing a role.
The roles currently supported are user
and admin
. user
is the default role if no role is specified.
Deleting a User
You can delete a user through:
client.deleteUser(id);
The argument id
is a string representing a given user’s ID.
Disabling and Enabling a User
You can disable a user through a client (opens in a new tab) object as follows:
client.disableUser(id);
In this case, id
is a string representing a given user’s ID, as stored within a user (opens in a new tab) object:
var user = client.createUser(email, roles);
String id = user.id;
client.disableUser(id);
Again, email
is a string and roles
is a list of strings, as per client.createUser()
.
You can reenable the user by calling the client object’s enableUser()
method, as follows:
var rsp = client.enableUser(id);
Json.print(rsp, 4);
Listing Users
You can list users through a client (opens in a new tab) object as follows:
var rsp = client.listUsers();
Json.print(rsp, 4);
Retrieving User Details
You can retrieve user details from the system as follows:
var rsp = client.getUser(String id);
Again, id
is a string ID uniquely identifying the user, for example, "auth0|XXXXXXXXXXXXXXXXXX"
.
Finding Users Using Email
You can look up a user’s details by specifying their email through the findUser()
function of the client:
var rsp = client.findUser("user@relational.ai")
Json.print(rsp, 4);
Managing OAuth Clients
OAuth clients can be managed with the following functions, provided you have the corresponding permissions:
var oa = client.createOAuthClient(String name);
or
var oa = client.createOAuthClient(String name, String[] permissions);
Here name
is a string identifying the client.
permissions
is a list of permissions from the following supported permissions:
create:accesskey
create:engine
create:oauth_client
create:user
delete:engine
delete:database
delete:oauth_client
list:accesskey
list:engine
list:database
list:oauth_client
list:permission
list:role
list:user
read:engine
read:credits_usage
read:oauth_client
read:role
read:user
rotate:oauth_client_secret
run:transaction
update:database
update:oauth_client
update:user
You can get a list of OAuth clients as follows:
var oacList = client.listOAuthClients();
Json.print(oacList, 4);
This is how to get details for a specific OAuth client, identified by the string id
:
var rsp = client.getOAuthClient(String id);
Here’s how to delete the OAuth client identified by the string id
:
var rsp = client.deleteOAuthClient(id);
You can find the OAuth client identified by the string id
as follows:
var rsp = client.findOAuthClient(id);
Each OAuth client has its own set of permissions, which determine the operations it can execute. Depending on the permissions, some operations, such as listing other users and creating or deleting engines, may fail. See the RAI Console Managing Users guide for more details.
Managing Engines
To query and update RelationalAI databases, you will need a running engine. The following API calls create and manage them.
Creating an Engine
You can create a new engine as follows. Note that the default size is XS
:
String engine = "java_sdk_engine";
var rsp = client.createEngine(engine);
Json.print(rsp, 4);
Or, you can specify the size:
String engine = "java_sdk_engine";
String size = "XS";
var rsp = client.createEngine(engine, size);
Json.print(rsp, 4);
API requests return a JSON value.
Here is a sample result for createEngine()
:
{
"id": "#########",
"name": "java_sdk_engine",
"region": "#########",
"account_name": "#########",
"created_by": "#########",
"created_on": null,
"deleted_on": null,
"size": "XS",
"state": "REQUESTED"
}
Valid sizes are given as a string and can be one of:
XS
(extra small).S
(small).M
(medium).L
(large).XL
(extra large).
Note: It may take some time before your engine is in the “PROVISIONED” state, where it is ready for queries. It will be in the “PROVISIONING” state before that.
To list all the engines that are currently provisioned, you can use listEngines()
:
var rsp = client.listEngines();
Json.print(rsp, 4);
If there is an error with the request, an HTTPError
exception will be thrown.
Most of the API examples below assume there is a running engine (in the “PROVISIONED” state) in the engine
string variable, and a test database in the database
string variable:
// replace with your values for testing:
String database = "mydatabase";
String engine = "myengine";
Deleting an Engine
You can delete an engine with:
var rsp = client.deleteEngine(engine);
Json.print(rsp, 4);
If successful, this will return:
{
"id": "#########",
"name": "java_sdk_engine",
"region": "#########",
"account_name": "#########",
"created_by": "#########",
"created_on": "2022-09-07T10:34:16.460Z",
"deleted_on": null,
"size": "XS",
"state": "DELETE_REQUESTED"
}
Note that since RelationalAI decouples computation from storage, deleting an engine does not delete any cloud databases. See Managing Engines for more details.
Getting Info for an Engine
You can retrieve the details for a specific engine with getEngine()
:
var rsp = client.getEngine(engine);
Json.print(rsp, 4);
An HTTPError
exception will be thrown if the engine specified in getEngine()
does not exist.
Managing Databases
Creating a Database
You can create a database by calling a client object’s createDatabase()
method, as follows:
var rsp = client.createDatabase(database, engine);
Json.print(rsp, 4);
The result from a successful create_database
call will look like this:
{
"id": "#########",
"name": "mydatabase",
"region": "#########",
"account_name": "#########",
"created_by": "#########",
"deleted_on": null,
"deleted_by": null,
"default_compute_name": null,
"state": "CREATED"
}
Cloning a Database
You can use cloneDatabase()
to clone a database by specifying source
and destination
arguments:
String sourceDB = database;
String targetDB = "cloneDB";
var rsp = client.cloneDatabase(targetDB, engine, sourceDB);
Json.print(rsp, 4);
With this API call, you can clone a database from mydatabase
to "cloneDB"
, creating an identical copy.
Any subsequent changes to either database will not affect the other.
Cloning a database fails if the source database does not exist.
You cannot clone from a database until an engine has executed at least one transaction on that database.
Retrieving Database Details
You can view the details of a database using the getDatabase()
method of a client object:
var rsp = client.getDatabase(database);
Json.print(rsp, 4);
The response is a JSON object.
If the database does not exist, an HTTPError
exception is thrown.
Listing Databases
Using listDatabases()
will list the databases available to the account:
var rsp = client.listDatabases();
Json.print(rsp, 4);
A variation of the listDatabases()
method takes a parameter state
as input that can be used to filter databases by state.
Example states are: “CREATED”, “CREATING”, or “CREATION_FAILED”.
var rsp = client.listDatabases("CREATED");
Json.print(rsp, 4);
Deleting Databases
You can delete a database with deleteDatabase()
if the client has the right permissions.
The database is identified by its name, as used in createDatabase()
:
var rsp = client.deleteDatabase(database);
Json.print(rsp, 4);
If successful, the response will be of the form:
{"name": "#########", "message": "deleted successfully"}
Deleting a database cannot be undone.
Rel Models
Rel models are collections of Rel code that can be added, updated, or deleted from a dedicated database. A running engine — and a database — is required to perform operations on models.
Loading a Model
The loadModel()
method of a client object loads a Rel model in a given database.
It is overloaded in two different variations:
loadModel(String database, String engine, String name, String model);
loadModel(String database, String engine, String name, InputStream model);
These methods are equivalent, with the small difference that the model is coming from an InputStream
or provided as a String
.
Here is an example where the model "mymodel"
is provided as a String
:
String modelString = "def R = \"hello\", \"world\"";
var rsp = client.loadModel(database, engine, "mymodel", modelString);
Json.print(rsp, 4);
Similarly, if you want to read the model from a file and load it in the database:
String filename = "hello.rel";
var name = "mymodel";
var input = new FileInputStream(filename);
var rsp = client.loadModel(database, engine, name, input);
Json.print(rsp, 4);
Loading Multiple Models
In addition to the simple versions of providing the model either through a String
or an InputStream
, you can also provide a Map
with a collection of models, together with their names.
In this case you need to use the loadModels()
method:
loadModels(String database, String engine, Map<String,String> models);
Here is an example that loads multiple models at once:
HashMap<String, String> myModels = new HashMap<String, String>() {{
put("model1", "def R = {1 ; \"hello\"}");
put("model2", "def P = {2 ; \"world\"}");
}};
var rsp = client.loadModels(database, engine, myModels);
Note that if the database already contains an installed model with the same given name, it is replaced by the new source.
Deleting Models
You can delete installed models from a database as follows:
var rsp = client.deleteModel(database, engine, model_name);
Json.print(rsp, 4);
Note that model_name
is a string vector containing the names of the model or models to be deleted.
Listing Installed Models
You can list the models in a database using the following code:
var rsp = client.listModelNames(database, engine);
Json.print(rsp, 4);
This returns a JSON array of names.
To see the contents of a named model, you can use:
String modelname = "mymodel";
var rsp = client.getModel(database, engine, modelname);
Json.print(rsp, 4);
modelname
is the name of the model.
You can also list all models and their code using listModels()
:
var rsp = client.listModels(database, engine);
Json.print(rsp, 4);
Querying a Database
The high-level API method for executing queries against the database is execute()
.
The function call blocks until the transaction is completed or there are several timeouts indicating that the system may be inaccessible.
It specifies a Rel source, which can be empty, and a set of input relations.
There are two overloaded versions of execute()
:
execute(String database, String engine, String source, boolean readonly);
execute(String database, String engine, String source,
boolean readonly, Map<String,String> inputs);
Here is an example of a read query using execute()
:
var rsp = client.execute(
database,
engine,
"def output = {1;2;3}",
true
);
System.out.println(rsp);
This gives the output:
[{"relationId":"/:output/Int64","table":[1,2,3]}]
Write queries, which update base relations through the control relations insert
and delete
,
must use readonly=false
.
Here is an API call to load some CSV data and store them in the base relation my_base_relation
:
String data = new StringBuilder()
.append("name,lastname,id\n")
.append("John,Smith,1\n")
.append("Peter,Jones,2\n")
.toString();
String source = new StringBuilder()
.append("def config:schema:name=\"string\"\n")
.append("def config:schema:lastname=\"string\"\n")
.append("def config:schema:id=\"int\"\n")
.append("def config:syntax:header_row=1\n")
.append("def config:data = mydata\n")
.append("def delete[:my_base_relation] = mybase-relation\n")
.append("def insert[:my_base_relation] = load_csv[config]\n")
.toString();
HashMap<String, String> inputs = new HashMap<String, String>() {{
put("mydata", data);
}};
var rsp = client.execute(
database,
engine,
source,
false,
inputs
);
System.out.println(rsp);
The RelationalAI SDK for Java also supports asynchronous transactions, through executeAsync()
that takes similar parameters to execute()
.
In summary, when you issue a query to the database, the return output contains a transaction ID that can subsequently be used to retrieve the actual query results.
executeAsync()
is defined similarly to execute()
, but in this case the running process is not blocked:
var rsp = client.executeAsync(
database,
engine,
"def output = {1;2;3}",
true
);
Then, you can poll the transaction until it has completed or aborted. Finally, you can fetch the results:
var id = rsp.transaction.id;
var transaction = client.getTransaction(id).transaction;
if ( "COMPLETED".equals(transaction.state) || "ABORTED".equals(transaction.state) ) {
var results = client.getTransactionResults(id);
System.out.println(results);
}
Similarly to client.getTransactionResults()
, you can also get metadata and problems for a given transaction ID:
var metadata = client.getTransactionMetadata(id);
var problems = client.getTransactionProblems(id);
The query size is limited to 64MB. An HTTPError
exception will be thrown if the request exceeds this API limit.
Getting Multiple Relations Back
In order to return multiple relations, you can define subrelations of output
.
For example:
var rsp = client.execute(
database,
engine,
"def a = 1;2 def b = 3;4 def output:one = a def output:two = b",
true
);
var id = rsp.transaction.id;
var results = client.getTransactionResults(id);
System.out.println(results);
This gives the following output:
{"relationId":"/:output/:one/Int64","table":[1,2]},
{"relationId":"/:output/:two/Int64","table":[3,4]}
Result Structure
The response contains the following fields:
Field | Meaning |
---|---|
transaction | Information about transaction status, including identifier. |
metadata | A JSON string with metadata about the results and their data type. |
results | A JSON string with the query output information. |
problems | Information about any existing problems in the database — which are not necessarily caused by the query. |
Each query is a complete transaction, executed in the context of the provided database.
Problems are also a JSON string with the following fields:
Field | Meaning |
---|---|
error_code | The type of error that happened, for example, "PARSE_ERROR" . |
is_error | Whether an error occurred or there was some other problem. |
is_exception | Whether an exception occurred or there was some other problem. |
message | A short description of the problem. |
path | A file path for the cases when such a path was used. |
report | A long description of the problem. |
type | The type of problem, for example, "ClientProblem" . |
Specifying Inputs
The execute()
member function takes an optional inputs
Map
that can be used to map relation names to string constants for the duration of the query.
For example:
var rsp = client.execute(
database,
engine,
"def output = foo",
true,
new HashMap<String, String>() {{ put("foo", "asdf"); }}
);
System.out.println(rsp);
This will return the string "asdf"
back.
Functions that transform a file and write the results to a base relation can be written like this.
The Rel calls load_csv
and load_json
can be used in this way, via the data parameter, to write results to a base relation.
See, for example, the sample code using load_csv
in Querying a Database.
Loading Data: load_csv
and load_json
As a convenience, the Java API includes loadCSV
and loadJSON
member functions in the client class.
These are not strictly necessary, since the load utilities in Rel itself can be used
in a non-read-only execute()
query that uses the inputs
parameter.
See, for example, the sample code using load_csv
in Querying a Database.
The Java function loadCSV()
loads data
and inserts the result into the base relation named by the relation
argument.
Additionally, loadCSV()
attempts to guess the schema of the data.
For more control over the schema, use a non-read-only execute()
query using the inputs
option:
loadCsv(String database, String engine, String relation, InputStream data);
loadCsv(String database, String engine, String relation,
InputStream data, CsvOptions options);
loadCsv(String database, String engine, String relation,
String data);
loadCsv(String database, String engine, String relation,
String data, CsvOptions options);
The CSVOptions (opens in a new tab) class allows you to specify how to parse a given CSV file.
Through a CSVOptions
object you can specify, for example, the delimiter and the escape character of a given file.
Similarly to loadCSV()
, loadJson()
loads the data
string as JSON and inserts it into the base relation named by the relation
argument:
loadJson(String database, String engine, String relation, InputStream data)
loadJson(String database, String engine, String relation, String data)
Example:
var rsp = client.loadJson(database, engine, "myjson", "{\"a\" : \"b\"}");
Note: In both cases, the relation
base relation is not cleared, allowing for multipart, incremental loads.
To clear it, you can do:
def delete[:relation] = relation
Listing Base Relations
You can list base relations as follows:
var rsp = client.listEdbs(database, engine);
This will list the base relations in the given database
.
The result is a JSON list of objects.
Transaction Cancellation
You can cancel an ongoing transaction as follows:
var rsp = client.cancelTransaction(id);
System.out.println(rsp);
The argument id
is a string that represents a transaction ID.