Skip to content
  • RKGMS
  • SDK GUIDES
  • Java

RelationalAI SDK for Java

This guide presents the API for the RelationalAI SDK for Java.

This guide presents the main features of the RelationalAI SDK for Java, used to interact with the Relational Knowledge Graph Management System (RKGMS).

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


RelationalAI/rai-sdk-java

It includes self-contained examples of the main API functionality. Contributions and pull requests are welcome.

Note: This guide applies to rai-sdk-java, the latest iteration of the Java SDK. The relationalai-sdk package is deprecated.

The last section describes how the different Console notebook cell types can be implemented with the Java SDK API.

Requirements

Check the rai-sdk-java repository for the latest version requirements to interact with the RKGMS 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 git repository:

git clone https://github.com/RelationalAI/rai-sdk-java

Next, you can build it using Maven. The SDK’s build lifecycle is managed through the standard mvn lifecycle commands. The following commands are issued within the rai-sdk-java directory:

cd rai-sdk-java

To compile the SDK:

mvn compile

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.

If you’d like to compile, package, run the tests, and then install the SDK:

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 would like to compile, package, and install without running any tests.

You can clean up your source tree using:

mvn clean

Using the Java SDK as a Maven Dependency

In order to use the rai-sdk-java SDK, 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, also 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

To connect to the RAI Server using the Java SDK, you need a configuration file. See the SDK Configuration guide 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 simply 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, 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 member function of a Client 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.

Disabling and Enabling a User

You can disable a user through a Client object as follows:

client.disableUser(id);

In this case, id is a string reflecting a given user’s ID, as stored within a User 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 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:compute
  • create:oauth_client
  • create:user
  • delete:compute
  • delete:database
  • delete:oauth_client
  • list:accesskey
  • list:compute
  • list:database
  • list:oauth_client
  • list:permission
  • list:role
  • list:user
  • read:compute
  • 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);

Get details for a specific OAuth client, identified by the string id:

var rsp = client.getOAuthClient(String id);

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 or creating or deleting compute engines, may fail. Refer to the RAI Console Managing Users guide for further details.

Managing Engines

To query and update RAICloud 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 by your values for testing:
String database = "mydatabase";
String engine = "myengine";

Deleting an Engine

An engine can be deleted 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 RAICloud decouples computation from storage, deleting an engine does not delete any cloud databases. See Managing Engines for more details.

Getting Info for an Engine

The details for a specific compute engine can be retrieved 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 only succeeds if the source database already exists.

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

A database can be deleted 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 Model Sources

Rel model sources are collections of Rel code that can be added, updated, or deleted from a particular database. Since they update a database, a running engine — and a database — is required to perform operations on sources.

Installing Rel Model Sources

The loadModel() method of a client object installs a Rel model source in a given database. The loadModel() method 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 is provided as a String:

String sourceString = "def R = \"hello\", \"world\"";
var rsp = client.loadModel(database, engine, "mysource", sourceString);
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 = "mysource";
var input = new FileInputStream(filename);
var rsp = client.loadModel(database, engine, name, input);
Json.print(rsp, 4);

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("source1", "def R = {1 ; \"hello\"}");
    put("source2", "def P = {2 ; \"world\"}");
}};
var rsp = client.loadModels(database, engine, myModels);

Note that if the database already contains an installed source with the same given name, it is replaced by the new source.

Deleting a Rel Model Source

You can delete a source from a database using the deleteModel() method:

var rsp = client.deleteModel(database, engine, "mysource");
Json.print(rsp, 4);

Listing Installed Rel Model Sources

You can list the sources 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 source, use:

String sourcename = "mysource";
var rsp = client.getModel(database, engine, sourcename);
Json.print(rsp, 4);

where sourcename is the name of the model.

You can also list all models and their sources using listModels():

var rsp = client.listModels(database, engine);
Json.print(rsp, 4);

Querying a Database

The high-level API method for running a single query/transaction 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);

Queries meant to update base relations with insert and delete must use readonly=false.

Here is an example of 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]}]

As another example, here is an API call to load some CSV data and store it 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 similar 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);
}

Similar 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

As in the RAI Console, if you want 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);

Giving the output:

{"relationId":"/:output/:one/Int64","table":[1,2]}, 
{"relationId":"/:output/:two/Int64","table":[3,4]}

Result Structure

The response contains the following fields:

FieldMeaning
transactionInformation about transaction status, including identifier.
metadataA JSON string with metadata about the results and their data type.
resultsA JSON string with the query output information.
problemsInformation about any existing problems in the DB — 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:

FieldMeaning
error_codeThe type of error that happened, for example, "PARSE_ERROR".
is_errorWhether an error occurred or there was some other problem.
is_exceptionWhether an exception occurred or there was some other problem.
messageA short description of the problem.
pathA file path for the cases when such a path was used.
reportA long description of the problem.
typeThe 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, analogous to the file upload feature of Rel Console notebooks. 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 easily 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 a loadCSV and loadJSON member function 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 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, issue a non-read-only query of the form:

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.

Notebook Cell Types

As explained in Working with RAI Notebooks there are four notebook cell types: Query, Install, Update, and Markdown. This section describes how the three cell types Query, Install, and Update map to Java SDK API calls.

Query Cells

The Query cell in a Rel Console notebook corresponds to an execute() (or executeAsync()) function call, as shown below:

var rsp = client.execute(
    database,
    engine,
    "def output = {(1,); (2,); (3,)}",
    true
);

Note that no rules/definitions are persisted in this case.

Install Cells

To persist derived relation definitions, use the loadModel() API function of a Client object. That is, the Install cell in a Rel Console notebook corresponds to the loadModel() Java function call, as shown below:

var rsp = client.loadModel(
    database,
    engine,
    "arity1_k_def",
    "def k = {2;3;50}"
);

Check that the relation above was persisted using the execute() API call:

var rsp = client.execute(database, engine, "def output = k", true);
System.out.println(rsp);

Output:

[{"relationId":"/:output/Int64","table":[2,3,50]}]

Update Cells

The Update cell in a Rel Console notebook corresponds to an execute() function call with the parameter readonly=false. For example:

var rsp = client.execute(
    database,
    engine,
    "def insert:employee = {(1, \"Han Solo\"); (2, \"Bart Simpson\")}",
    false
);

You can modify the employee base relation:

var rsp = client.execute(
    database,
    engine,
    "def insert:employee = {(3, \"King\"); (4, \"Queen\")}",
    false
);

You can now query the modified employee base relation:

var rsp = client.execute(
    database,
    engine,
    "def output=employee",
    false
);
System.out.println(rsp);
[
    1,
    2,
    3,
    4
],
[
    "Han Solo",
    "Bart Simpson",
    "King",
    "Queen"
]

To update base relations, always use the readonly=false parameter in the execute() call.

Was this doc helpful?