Skip to content
Working with Queries

Working With Queries in the RAI Console

A short guide to working with queries in the RAI Console.

The RAI Console features a Query Editor that you can use to view and manage the contents of your database.

Using the Query Editor

With the Query Editor, you can experiment with issuing query requests. The Output panel will display the results in the same way as you would see them in a RAI notebook.

initial view of the Query Editor

Queries are not persisted in the database. Instead, queries are saved in your browser’s local storage, and are available until you delete them, as long as you log into the Console using the same browser and same account.


Queries are stored separately from databases. If you create a query for one database and open another database, the query will remain in the Query Editor — queries remain as long as you are using the same browser on the same machine — but may not work.

Running Queries

To run a query:

  1. Click + in the Query Editor to add a new query.
add new query
  1. Enter a query into the Query Editor.
  2. Click Run.

Query results appear in the Query Output panel.

Note that the Output panel displays the amount of time the query has been running in the upper right-hand corner. You can cancel queries that are running too long. See Canceling a Query below.

The query remains active until you switch to another query. If you make changes to data, the query automatically updates.

For example, say the data in a model read as follows:

// write query
module store
    def office = {
      "Los Angeles";
    def product = {
      (1, "Laptops");
      (2, "Desktops");
      (3, "Phones")

Running a query that reads def output = store:product produces the following result:


While you have a query open, its results will update automatically when data are changed.

If, in the example above, you modify the definition of store:product to add (4, "Keyboards") while the query is running, the results will update as follows:


The query size is limited to 64MB. An HTTPError exception will be thrown if the request exceeds this limit.

Including Definitions

You can also include definitions in a query in order to simulate the results of making changes to data.

For example, to simulate adding a row to the store:product definition that you installed above, enter the following into the Query Editor:

def store:product = (5, "Memory")
def output = store:product

When you run the query, the results will read:


Note that 5, "Memory" is included in the output even though the installed model does not include this entry.

Using Autocomplete

The Query Editor has an Autocomplete feature that fills in the rest of a term when you begin typing. Autocomplete includes all Library relations as well as special Unicode characters, such as mathematical operation symbols, relation operation symbols, and Greek letters.

To use Autocomplete:

  1. Begin typing desired text, such as parse.
  2. Press Control+Space (PC) or Command+Esc (Mac). A pull-down menu opens with Autocomplete suggestions.
  3. Select desired text by either clicking it with the mouse or selecting it using the down/up arrows and pressing Enter or Tab.

For example, if you type parse and press Control+Space, Autocomplete offers a list of options: parse_date, parse_datetime, parse_decimal, and so on. To choose parse_datetime, for example, select parse_datetime from the pull-down menu.

To add special Unicode characters:

  1. Type \ and press Control+Space (PC) or Command+Esc (Mac).
  2. Select desired character from the pull-down menu.

For example, to add subset of (⊂):

  1. Type \.
  2. Press Control+Space (PC) or Command+Esc (Mac).
  3. Select \subset from the pull-down menu.

To close Autocomplete, press Esc or click outside the Autocomplete.

Commenting Out Query Segments

To comment out part of a query, you can add // to the beginning of a line. You can also comment out a section of a query by adding /* to the beginning of a section and */ to the end of the section.

Changing Query Output Display

By default, queries display in logical form. You can also choose to display query results in either raw or physical form.

LogicalShows results as they appear in Rel.
RawShows results as they are stored in the database (underlying data) in JSON.
PhysicalShows results as they are stored in the database in table.

To change a query result’s format:

  1. Click the three dots at the far right of the Output window.
  2. Choose Physical or Raw for output.
change query display type

Using Find and Replace

The Query Editor has a find-and-replace feature that lets you search the current Query tab for a string, and then replace this string.

To use Find and Replace:

  1. Press Control+F (PC) or Command+F (Mac). A panel opens at the bottom of the Editor:
Find and replace
  1. Enter a string in the top box and press Enter (PC) or Return (Mac). Search results are highlighted in the Query Editor.
  2. Enter a replacement string in the bottom box and click replace or replace all.

Note that if you select text in the Editor and then press Control+F (PC) or Command+F (Mac), the Find field will automatically be populated with the selected text.

Available options are:

match caseRespects case sensitivity. For example, if you enter “Student” into the Find field and select match case, the Console will find “Student” but not “student.”
regexpUses regular expressions in both Find and Replace fields.
by wordFinds only whole words (that is, words enclosed in white spaces). For example, if you enter “story” into the Find field and select match case, the Console will find “story” but not “history.”

Navigating Search Results

To select the next search result, click next or press F3 or Control+G (PC) or Command+G (Mac). To select the previous search result, click previous or press Shift+F3 or Control+G (PC) or Command+G (Mac). You can also select all results by clicking all.

Using Regular Expression

You can use regular expressions in search. For example, if you want to search for only numerals, type the following in the Find field: [0-9].

Regular expressions make use of special characters: .[{()\^$|?*+. To search for these characters, you need to escape them with a backslash \. For example, if you need to find ., type \. in the Find field.

You can also capture and replace groups. In the Find field, enter parentheses () to indicate a capturing group, such as (.*?).

In the Replace field, you can reference groups with numbers preceded by $, such as $1.

Canceling a Query

While a query is running, you can cancel the query.

To cancel a query, click Cancel on the right-hand side of the Query Editor.

query cancel button

Naming a Query

By default, queries are unnamed. When you create a new query, the query is called Query_1. Subsequent new queries are named Query_2, Query_3, and so on.

You can rename the query by double-clicking the query’s tab and entering a new name in the window that opens.

Hiding the Query Editor

You can show or hide the Query Editor by clicking Show/Hide Queries on the right-hand side of the Console.

Show or Hide the Query Editor

Working With Base Relation Data

The Query Editor lets you insert and delete records from a base relation by turning off the Read-Only switch. When the Read-Only switch is turned off, code entered into the Query Editor runs directly against stored base relation data. For more information on working with base relations, see Working With Base Relations.


You cannot use the Query Editor to make changes to models. To make changes to models, you need to use the Model Editor. See Working With Models for more details.

You can, however, use the Query Editor to simulate changes to a base relation by leaving the Read-Only switch on.

For example, say you have a base relation with the following data on yearly rainfall in California cities (from the US National Centers for Environmental Information (opens in a new tab)):


You can create this relation in the Query Editor by turning the Read-Only switch off and entering the following code. This code uses the Rel relation load_csv to simulate loading the contents of a CSV file into a base relation called rainfall. The code creates a schema with two columns: :city, "string" and :inches, "float". For more information on specifying schemas when importing CSV data, see Specifying Column Types (File Schema) in the CSV Import guide.

// write query
def config:data = """
def config:schema=(:city, "string") ; (:inches, "float") //creates a schema for the data
def csv = load_csv[config] //uses the Rel relation \stdlib{load_csv} to simulate loading a csv file
def insert[:rainfall](city,inches) = csv(:city, pos, city)
and csv(:inches, pos, inches) from pos //creates the relation "rainfall" and inserts into it from the relation "csv"

When you click Run, the code creates the relation rainfall, which appears in the Object Tree under Data.

A base relation created

Read-Only mode remains deactivated until you switch it back on. This means that any new queries will make changes to base relation data until you switch Read-Only mode back on.

Note that nothing appears in the Output window. That’s because this code does not return a result.

Updating Base Relation Data

When you run queries with the Read-Only switch turned off, you can use the Query Editor to update base relations: You can insert rows into and delete rows from base relations.

For example, to insert a new record into the rainfall relation defined above, you would turn off the Read-Only switch and enter code along the following lines:

// write query
def insert[:rainfall] = ("Napa", 26.7)

If you now query rainfall, you’ll see that the data for Napa have been added:

// read query
def output = rainfall

Testing Changes to Base Relation Data

You can also use the Query Editor to simulate changes to a base relation without changing data. To do so, incorporate an insert or delete statement into the Query Editor and query the data with the Read-Only switch turned on.

You can test this functionality by setting up a simple calculation on the rainfall relation. The following code determines the average rainfall across cities:

// read query
def output:avg = average[rainfall]

Given the data above, this calculation initially returns an average of 22.91111111111111.

You can modify this code block to include a simulated addition to the rainfall relation. You can use the yearly rainfall for Santa Cruz, a city whose yearly rainfall is slightly higher than the average you just calculated:

// read query
def insert[:rainfall] = ("Santa Cruz", 30.6)
def output:avg = average[rainfall]

When you run this query, the RKGS calculates average[rainfall] with the new row included, returning an average of 23.68.

Shortcuts for Using the Query Editor

Here are some shortcuts for using the Query Editor:

  • Command+S or Control+S saves the query.
  • Shift+Enter saves and runs the query.
  • Control+Enter creates a new query.
Was this doc helpful?