IDB: Software (2)

Using the REAL relational algebra interpreter

REAL is command-line Java application to parse and execute Relational Algebra queries. It is released under the MIT license, so you can basically do whatever you like with it. But please keep in mind that REAL is an educational tool not meant for production applications. Moreover, like all software, it may contain bugs; if you think you found one, please consider submitting a bug report at https://git.ecdf.ed.ac.uk/pguaglia/real/issues

Prerequisites

Java Runtime Environment 11 (since REAL v0.7), which should be available on all DICE student machines.

Downloading

You can download the latest version from https://git.ecdf.ed.ac.uk/pguaglia/real/-/releases. We will use REAL v0.7 or above.

From a shell (for example, on DICE), you can get a copy of REAL using the wget command following by the download link you find in the release page. For example, for version 0.7, you would issue:

wget https://git.ecdf.ed.ac.uk/pguaglia/real/uploads/4401134f7828179c06c92360d835243b/real-0.7.jar

A copy of the latest REAL version (currently 0.7) is hosted on AFS at

/afs/inf.ed.ac.uk/group/teaching/dbs/2024/real-0.7.jar

and it is available when working on a DICE machine (in person or connected remotely via ssh). I suggest creating a symbolic link to the JAR file in a convenient location (e.g., your home directory); to do that, navigate to the directory where you want to create the symbolic link, and issue the following command:

ln -s /afs/inf.ed.ac.uk/group/teaching/dbs/2024/real-0.7.jar .

(pay attention to the last dot, which means "the current directory", in the above command).

Installing

The downloaded JAR file can be moved to a location of your choice. I suggest you keep it in your home folder in AFS, or in your working directory for IDB-related stuff (if you have one).

Running

In a shell under Linux or Mac, simply invoke java -jar real-<version>.jar (replacing <version> with the appropriate version number) from the directory where the JAR file is located (or specify its path if working from a different directory).

On Windows, you must also explicitly specify the UTF-8 character encoding for the Java VM (otherwise you get mangled characters), as follows:

java -D"file.encoding=UTF-8" -jar real-<version>.jar

I recommend running REAL in a shell on DICE, to avoid potential compatibility issues.

Using REAL's interactive prompt

You can issue special commands (which start with a dot and are not terminated by semicolon) and relational algebra expressions (which are terminated by semicolon).

Commands. To print the list of commands accepted by REAL, issue the command .help

Expressions. For details on the Relational Algebra syntax accepted by REAL, issue the command .syntax

Unfortunately, some features and constructs (such as view definitions and CSV output in batch mode) are not yet documented in the in-app help, but their description is available in the CHANGELOG file in the repository.

Executing queries from text files

In interactive mode, one can simply copy the file contents to the clipboard using a text editor, and then paste them into the REAL console.

In batch mode, one can run a query from a text file using the cat command (available on all DICE machines), as follows:

java -jar real-<version>.jar -d SCHEMAFILE -q "$(cat QUERYFILE)"

For example, if the schema file is schema.json, the query file is query.txt, and these are both in the same directory as REAL, then one would issue:

java -jar real-<version>.jar -d schema.json -q "$(cat query.txt)"

Unfortunately, there is not yet a way to directly execute a query file within REAL's interactive command prompt.

Evaluation under bag semantics

In interactive mode, this is enabled by issuing the command .eval bag at the prompt.

In batch mode, evaluation under bag semantics can be enabled with the -e argument:

java -jar real-<version>.jar -d SCHEMAFILE -q "$(cat QUERYFILE)" -e bag