Skip to content
  • RKGMS
  • RAI CONSOLE
  • Working with RAI Notebooks

Working with RAI Notebooks

A short guide to working with RelationalAI notebooks.

RelationalAI notebooks are a great way to interact with the RKGMS database, visualize data, and develop your next data science project.

Managing Notebooks

You can create, delete, export, and import notebooks through the RAI Console.

Creating Notebooks

To create a notebook:

  1. Right-click on Notebooks at the bottom of the object tree on the left-hand side of the Console and choose Create.
create notebook
  1. In the window that opens, enter a name for the notebook and click Create.
🔎

On Mac computers, right-click is equivalent to Ctrl-click.

Deleting Notebooks

You can delete notebooks from the Object Tree.

Before doing so, it is best practice to:

  1. Export the notebook following the steps below so that you can recover it later if necessary.
  2. Check with other team members to make sure they are not using the notebook. The notebook will be unrecoverable once deleted.

To delete a notebook:

  1. Right-click the notebook you wish to delete and choose Delete.
  2. In the confirmation message that appears, click Delete.

The notebook disappears from the Object Tree and is removed from the database.

Exporting Notebooks

You can export notebooks as JSON files for archiving and sharing purposes. Exported notebooks can then be imported by other users.

To export a notebook:

  1. Either: Right-click on the notebook you wish to export and choose Export.

    OR

    Click the three dots in the upper right corner of an opened notebook and choose Export Notebook

  2. In the dialog box that opens, choose Save.

The notebook saves in your Downloads folder with the default name \<notebook-name\>.json.

Importing Notebooks

You can import notebooks either directly into the Console or into a notebook that you’ve opened in the Console.

To import a notebook:

  1. Either: Right-click on Notebooks at the bottom of the object tree on the left-hand side of the Console and choose Import.

    OR

    Click the three dots in the upper right corner of an opened notebook and choose Import Notebook

  2. Browse to the location of the notebook file and click Open.

When you import a notebook into an existing notebook, the entire existing notebook is overwritten with the contents of the imported notebook. This has the effect of deleting the existing notebook. Before overwriting an existing notebook, it is best practice to:

  1. Export the notebook following the steps below so that you can recover it later if necessary.
  2. Check with other team members to make sure they are not using the notebook. The notebook will be unrecoverable once overwritten.

Printing Notebooks

You can print the notebook by clicking the three dots in the upper-right corner of an opened notebook and choosing Print Notebook.

Working with Cells

RelationalAI notebooks use four different types of cells. When you open a new notebook, you’ll see one cell with a default type of Query.

To select a different cell type, use the pull-down menu at the top left of the cell.

To add a new cell, mouse over the area above or below a cell and click the ”+” icon. The ”+” icon above adds a cell before the current cell, while the ”+” icon below adds a cell after the current cell. You can also use Ctrl-Enter to run a cell’s contents and create a new cell below the current cell.

To hide a cell, mouse over the area to the left of a cell and click the Toggle Folding (eye) icon.

To delete a cell, click the “X” icon in the top right of the cell.

delete cell

Choosing a Cell Type

For each cell, you choose a cell type. These have different behaviors, and your choice of them depends on what you’re trying to achieve.

Cell TypeBehavior
QueryQuery values from the database, without making changes to the database.
InstallInstall definitions, entities, and logic into the database (see also the Installing Models guide). Definitions in these cells will be available to other cells in both the notebook and database.
UpdatePerform data updates that you do not want to run repeatedly, such as inserting and deleting tuples. You should generally use Update cells to manage base relations.
MarkdownWrite explanatory text in Markdown.

Query Cells

When you run code in a Query cell, the code only affects the cell itself. That is, Query cells execute read-only transactions. Any definitions that you create here will not be available to other cells in the notebook.

As their name suggests, Query cells are especially useful for querying values out of the RKGMS database.

To use a simple example, if you know that the database has a relation called city_population, you can run a query along the following lines to view data from city_population.

// query
 
def output = city_population

You can run more complex queries in Query cells as well:

// query
 
def city_population = {
    ("New York, NY", 8804190);
    ("Los Angeles, CA", 3898747 );
    ("Cambridge, MA", 118403);
}
 
def big_cities(city) = city_population[city] > 10^6
 
def output:cities = big_cities
def output:city_pop = city_population
query outputs

For queries with one or more definitions, the relation output is the one whose data is displayed in the notebook.

To display more than one relation as output, use the module syntax (i.e., output:cities) to give each output relation a name.

Note that the relations big_cities and city_population are defined only within this Query cell and can’t be accessed in any another cell.

To make city_population and big_cities available to other cells, you need to either:

  1. Put their definition in an Install cell or
  2. Write them to the database using an Update cell.

For more details, see Install Cells and Update Cells below.

Raw Data vs. Derived Relations

Rel notebooks are reactive: the results of a Query cell are automatically updated when you make changes elsewhere in the notebook or database that affect that query.

Install Cells

When you run code in an Install cell, this code is installed into the database and persisted. Definitions in these cells are permanently available to not only other cells in the notebook, but to all notebooks in the current database. Installed definitions are known as models. After you run an Install cell, models for the cell are visible in the Object Tree under </>Models/notebooks/<your-notebook>.

🔎

The code in Install cells is SHARED across all the notebooks in the same database. This lets you, for example, use one notebook as a “library” that is used by the other notebooks in the same database.

Let’s take a simple example, which defines a relation called city_population:

// install
 
def city_population = {
    ("New York, NY", 8804190);
    ("Los Angeles, CA", 3898747 );
}

Now, you can query or use city_population in any cell of any notebook in the current database.

For actual large-scale data, you should use a base relation. See the Update Cells Section below for more information.

query output

Since definitions add up, a new install cell with the following code

// install
 
def city_population = ("Cambridge, MA", 118403)

adds “Cambridge, MA” to the relation city_population(without overwriting it). That is, the new code is unioned with the original definition. We can verify the update by noting that the output of Query cell with city_population lists now three entries.

query output

Because our notebooks are reactive, the Query cell updates automatically.

Install cells are generally useful to organize your data modeling. You can even refer to relations you have defined in other Install cells. For example, you can use the following code to define big_cities as:

// install
 
def big_cities(city) = city_population[city] > 10^6

You can see the results for big_cities by entering it into a Query cell:

query output

If you decide to change the definition of a big city in your database, you simply modify the code block and run it again.

🔎

If you want to change a definition, it is best to do so in the same Install cell. Changing a definition in a separate Install cell will result in a union of the two definitions.

For instance, if you modify the code above — in the same install cell — to read as follows, a big city is now any city with a population greater than 100,000 instead of 1,000,000.

// install
 
def big_cities(city) = city_population[city] > 10^5
big cities

For the most part, you will want to use Install cells to run code that defines new logic on top of existing data (“views” on data) but does not change the data themselves. Check out the Installing Models guide for more details about installing Rel programs.

For projects with small data, you can define the data in derived relations using Install cells. For larger datasets, the best practice is to use base relations. For more information on base relations, see Updating Data: Working with Base Relations. To create, delete, or change base relation data you need to use Update cells.

Naming Models

When you open a database in the RelationalAI Console, data, models, and notebooks are listed in the Object Tree. When you run an Install cell, a new model is added to the list.

You can name your model by changing the text in the box that appears to the right of the Cell Type drop-down menu. This is useful if you want to edit the code for the Install cell directly from the models list.

big cities

Update Cells

Update cells let you change the data for what are known as base relations: this might be a table of employees and their related information, or a list of inventoried products.

Base relations are stored on disk, and generally — though not always, as in the initial examples below — contain data from external sources; they are the “raw data” for the database. In contrast, derived relations are generally derived from logic applied to base relations. For more information on base relations and derived relations, see Updating Data: Working with Base Relations.

After you run an Update cell, base relations created in the cell are visible in the Object Tree under </>Data/.

For example, you might use def delete:employee = employee to clear out the base relation called “employee”, or def insert:employee = "Clarissa Dalloway" to insert “Clarissa Dalloway” into this employee relation.

In other words, Update cells are transactional; changes made with Update cells persist in the database, even if you delete the cell’s code later.

You can think of Update cells as “action” or “execute” cells. They run only when you run them manually, by clicking the Run button (the triangle at the right of the input pane) or pressing SHIFT + ENTER.

🔎

Unlike Query cells, Update cells do not run automatically when you make changes elsewhere in the notebook.

To add data to a base relation called employee, for example, you could run the following in an Update cell:

// update
 
def insert:employee = {(1, "Han Solo"); (2, "Bart Simpson")}

The code runs once, and the employee relation appears as follows:

employee relation

Later, in the same cell, you can run similar code to add data to employee:

// update
 
def insert:employee = {(3, "Tyrone Slothrop"); (4, "Clarissa Dalloway")}

Again, the code runs once, and employee now contains the following data:

employee

You could also delete data by using code along the following lines:

// update
 
def delete:employee = (3, "Tyrone Slothrop")

Now, employee appears as follows:

employee

If you had run def insert:employee = {(3, "Tyrone Slothrop"); (4, "Clarissa Dalloway")} in an Install cell, this delete would not work, because the Install cell re-inserts the data every time it runs. That’s one reason to make changes to data using Update cells.

Uploading Files

You can upload CSV or JSON data directly using Update cells.

🔎

You can upload files up to 64MB in size. If you try to upload a file larger than 64MB, you will receive a validation error. This limit applies to local files only; you can import larger files from cloud sources. See Importing CSV Data or Importing JSON Data for more details.

To upload a CSV file:

  1. Select Update as the cell type.
  2. Click the Add Input icon at the top left of the cell.
  3. Enter a name for the relation, such as employee_data.
  4. Choose a file with a valid CSV format to upload (max. 64MB), and enter code along the following lines:
def config[:data] = employee_data
def insert:employee = lined_csv[load_csv[config]]
🔎

The lined_csv utility saves the row number in a CSV as the key.

lined_csv
  1. Click the Run button (the triangle at the right of the input pane) or press SHIFT + ENTER.

For more information on importing CSV data, see CSV Import.

To upload a JSON file:

  1. Select Update as the cell type.
  2. Click the Add Input icon at the top left of the cell.
  3. Enter a name for the relation, such as uploaded_json.
  4. Choose a file with valid JSON to upload (max. 64MB), and enter code along the following lines:
def config[:data] = uploaded_json
def insert:myjson = load_json[config]
  1. Click the Run button (the triangle at the right of the input pane) or press SHIFT + ENTER.

For more information on importing JSON data, see JSON Import and Export.

More generally, this file upload mechanism can be used to upload arbitrary string data, which can be further processed, as is the case above with the CSV and JSON string, or saved directly as a string-valued relation.

Markdown Cells

Markdown cells let you add explanatory text in the Markdown format. You can use any valid Markdown code:

## Notebook Explanation
Use _Markdown_ to add explanatory text to your notebook.

The cell with generated Markdown appears as follows:

markdown

Once you are satisfied with your Markdown, you can use Toggle Folding to hide the cell. To use Toggle Folding, mouse over the area to the left of a cell and click the “eye” icon.

Using Keyboard Shortcuts

Notebooks use key mappings that are similar to Emacs. Commonly-used examples appear below. For a complete list, see: https://codemirror.net/doc/manual.html#keymaps. Note: some of the key mappings in this link may not work with notebooks.

Keyboard ShortcutCommand
Shift-enterRun a cell.
Ctrl-enterRun a cell and add a new cell.
Alt-UpArrow (PC), Option-UpArrow (Mac)Move a line up.
Alt-DownArrow (PC), Option-DownArrow (Mac)Move a line down.
Shift-Alt-UpArrow (PC), Shift-Option-UpArrow (Mac)Copy line with cursor to new line above.
Shift-Alt-DownArrow (PC), Shift-Option-DownArrow (Mac)Copy line with cursor to new line below.
Ctrl-D (PC), Cmd-D (Mac)Delete entire line, including newline at the end.
Ctrl-Home (PC), Cmd-Up (Mac), Cmd-Home (Mac)Move cursor to start of cell.
Ctrl-End (PC), Cmd-End (Mac), Cmd-Down (Mac)Move cursor to end of cell.
Ctrl-U (PC), Cmd-U (Mac)Undo the last change to the selection.
Alt-Left (PC), Ctrl-A (Mac)Move the cursor to the start of the line.
TabIf something is selected, indent it by one indent unit. If nothing is selected, insert a tab character.
Ctrl-] (PC), Cmd-] (Mac)Indent the current line or selection by one indent unit.
Ctrl-[ (PC), Cmd-[ (Mac)Dedent the current line or selection by one indent unit.
Ctrl-A (PC), Cmd-A (Mac)Select the entire contents of the cell.
Alt-Left (PC), Ctrl-A (Mac)Move the cursor to the start of the line.
Alt-Right (PC), Ctrl-E (Mac)Move the cursor to the end of the line.
Alt-dragCreate multiple cursors.
Was this doc helpful?