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 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 Control+Click.

Deleting Notebooks

You can delete notebooks from the Object Tree.

Before doing so, it’s 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 want 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 the notebook you want 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 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 contents of the imported notebook overwrite the entire existing notebook. This has the effect of deleting the existing notebook. Before overwriting an existing notebook, it’s 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, hold the pointer over the area above or below a cell and click +. The ”+” icon above adds a cell before the current cell, while the ”+” icon below adds a cell after the current cell. You can also press Control+Enter to run a cell’s contents and create a new cell below the current cell.

To hide a cell, hold the pointer over the area to the left of a cell and click the Toggle Folding eye icon.

To delete a cell, click X 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 Installing Models. 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.

For 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 are 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 other cell.

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

  • Put their definition in an Install cell.

OR

  • Write them to the database using an Update cell.

For more details, see Install Cells and Update Cells.

🔎

RAI 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.

Consider this 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 Update Cells for more information.

query output

Since definitions add up, you can use a new Install cell to add a new definition. For example:

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

This code adds “Cambridge, MA” to the relation city_population, without overwriting it. That is, city_population is now the union of both the new and original definitions. You can verify the update by noting that the output of a Query cell with city_population now lists three entries.

query output

Because RAI 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:

// 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 can modify the code block and run it again.

🔎

If you want to change a definition, it’s 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. See Installing Models for more details on 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 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. By contrast, derived relations are generally derived from logic applied to base relations. For more information, 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 Run (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 reinserts 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 Add Input 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 file as the key.

lined_csv
  1. Click Run (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 Add Input at the top left of the cell.
  3. Enter a name for the relation, such as uploaded_json.
  4. Choose a file with a valid JSON format to upload (max 64MB), and enter code along the following lines:
def config[:data] = uploaded_json
def insert:myjson = load_json[config]
  1. Click Run (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 strings, 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’re satisfied with your Markdown, you can use Toggle Folding to hide the cell. To use Toggle Folding, hold the pointer 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 (opens in a new tab). Note: Some of the key mappings in this link may not work with notebooks.

Keyboard ShortcutCommand
Shift+EnterRun a cell.
Control+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.
Alt+Shift+UpArrow (PC), Option+Shift+UpArrow (Mac)Copy line with cursor to new line above.
Alt+Shift+DownArrow (PC), Option+Shift+DownArrow (Mac)Copy line with cursor to new line below.
Control+D (PC), Command+D (Mac)Delete entire line, including newline at the end.
Control+Home (PC), Command+Up (Mac), Command+Home (Mac)Move cursor to start of cell.
Control+End (PC), Command+End (Mac), Command+Down (Mac)Move cursor to end of cell.
Control+U (PC), Command+U (Mac)Undo the last change to the selection.
Alt+Left (PC), Control+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.
Control+] (PC), Command+] (Mac)Indent the current line or selection by one indent unit.
Control+[ (PC), Command+[ (Mac)Dedent the current line or selection by one indent unit.
Control+A (PC), Command+A (Mac)Select the entire contents of the cell.
Alt+Left (PC), Control+A (Mac)Move the cursor to the start of the line.
Alt+Right (PC), Control+E (Mac)Move the cursor to the end of the line.
Alt+DragCreate multiple cursors.
Was this doc helpful?