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:

RelationalAI/rai-sdk-java

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

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.

Was this doc helpful?

RelationalAI SDK for Java

Requirements

Installation

Using the RelationalAI SDK for Java as a Maven Dependency

Configuration

Creating a Client

Managing Users

Creating a User

Deleting a User

Disabling and Enabling a User

Listing Users

Retrieving User Details

Finding Users Using Email

Managing OAuth Clients

Managing Engines

Creating an Engine

Deleting an Engine

Getting Info for an Engine

Managing Databases

Creating a Database

Cloning a Database

Retrieving Database Details

Listing Databases

Deleting Databases

Rel Models

Loading a Model

Loading Multiple Models

Deleting Models

Listing Installed Models

Querying a Database

Getting Multiple Relations Back

Result Structure

Specifying Inputs

Loading Data: load_csv and load_json

Listing Base Relations

Transaction Cancellation

Loading Data: `load_csv` and `load_json`