RelationalAI VS Code Extension

Support for the Rel language and the RelationalAI Knowledge Graph Management System. For Rel documentation, see https://docs.relational.ai.

Quick tips

1. This extension is designed to work with your project directory as the folder that is open in VS Code. If you have a different directory open in VS Code --- perhaps a parent directory which contains multiple projects -- then open the project you want to work on in another VS Code window. Your models should be saved in a directory called model, your data loading code in a directory called update, and your queries in a directory called query.
2. The view you get when you click the RelationalAI icon in the Activity Bar on the left side of the VS Code window shows the state of your system in the cloud. In particular, when you click a cloud icon next to a model, you get an editor which displays and edits that model directly in the cloud. It is recommended that -- unless you want to edit the model specifically in the cloud -- you instead edit models locally in the model directory. Sync them to the cloud as needed with the command RelationalAI: Cloud Sync.
3. To see all available commands, do Ctrl+Shift+P (Cmd+Shift+P on Mac) to open the command palette and start typing RelationalAI.

Features

The RelationalAI VS Code extension provides several features:

1. Commands for sending selected code from any editor to the RelationalAI system and displaying the results in a rich-output webview that opens in a second pane. The output viewer supports Graphviz, Vega-Lite, and other MIME types.
2. A shift+enter keyboard shortcut for sending queries from a .rel or Markdown file.
3. A command called RelationalAI: Cloud Sync that can be used to keep your local collection of model files in sync with the models stored in the database in the cloud.
4. Rel Syntax highlighting:
   1. .rel files.
   2. Fenced code blocks in Markdown.
   3. In strings in Julia, Go, Python, Javascript, TypeScript, C#, Java files: sections of code between //beginrel and //endrel comments are syntax highlighted.
5. Hover help for standard-library relations and for user-defined base relations and derived relations.
6. Autocomplete for:
   1. Relations in the standard library.
   2. User-defined base relations and derived relations.
   3. Standard language features like insert and delete.
   4. Unicode symbols (like \sqrt).
7. Support for the VS Code Outline View, so users can see which relations are defined in the currently open .rel file and click on a relation name to navigate to its definition.
8. A RelationalAI Activity Bar icon that opens to a view of the user's engines, databases, and transactions. Databases and engines can be created and deleted, and transactions can be cancelled. The database items support several features:
   1. They open to show a list of base relations and derived relations, as well as a list of model files.
   2. They can be selected or deleted using action buttons.
   3. Their relations and relation dependencies can also be visualized. This works by generating Rel code that uses the graphviz relation.
9. Action icons for the relations in the Sidebar:
   1. You can click on a base or derived relation to reveal its contents in a table viewer.
   2. You can click on the cloud icon on a derived relation to open a view of the remote version of the model in a new editor. The remote views are editable. Alternatively, click on the document icon to open the local file in which that relation is defined.
10. Support for specifying query/update/install mode via a comment at the top of the block of code, or for sending fenced Markdown blocks that begin with ```rel type=install&id=profit.
11. CSV and JSON loaders, available via the command palette as RelationalAI: Load CSV and RelationalAI: Load JSON.
12. A task runner that allows you to specify workflows in configuration files and excute them.
13. A graph visualization of the dependency relationships between derived relations, including an interactive table for exploring the contents of each relation.

Getting started

Put your RelationalAI credentials into ~/.rai/config as explained in the RelationalAI Javascript SDK README. In VS Code, open a directory containing a RelationalAI project.

Use the RelationalAI button in the Activity Bar to select your database and engine, and run RelationalAI: Open Viewer from the command palette to open the output viewer. You can use the sidebar to create or delete an engine or database.

You can also open the database sidebar items to reveal lists of base and derived relations. If you click on a base or derived relation item in the sidebar, it will show the relation in the viewer. The derived relation items have action buttons --- one for the server and one for your local file system --- that will open an editor to the relation's first def statement in your models.

The graph button computes the dependencies between derived relations and as an interactive graph in a new pane. You can click on each item to show summary information about that relation and preview its contents.

You will also find a transactions list in the sidebar. You can use it to view the details of each transaction or to cancel a running transaction. Running transactions are indicated by an orange transaction icon, and the cancel button appears on the right side of the transaction item on hover.

Tasks

Format

You can specify sequences of operations to be performed in a task file, to be stored in a directory called task. Here's an example task file (task/example.toml, say):

[[step]]
name = "load helper relations"
mode = "install"
file_path = "model/helper"

[[step]]
name = "load data"
mode = "update"
file_path = "update/load-data.rel"
inputs = [
    { csv_data = "data/my-data.csv" }
]

[[step]]
name = "install remaining models"
mode = "install"
file_paths = [
    "model/business-logic.rel",
    "model/display-features.rel"
]

This example assumes that:

1. load-data.rel contains code like this:

   def config:data = csv_data
   def insert:my_relation = load_csv[config]
   

2. data/my-data.csv is a valid CSV containing the desired data.

3. model/helper is a directory containing .rel files.

Each step should include a name, a mode (which can be update, install, or query), either file_path or file_paths, and optionally inputs. The file_path or file_paths field should be a path or paths, respectively, to files relative to the root of the project directory. Alternatively, any entry may be a directory, in which case it will be expanded to all of the .rel files contained in that directory (recursively).

The inputs field should be a list of objects, each of which should have a single key-value pair. The key should be the name of a variable to be referred to in the Rel file or files, and the value should be the path to a file whose contents will be inserted for that variable in the Rel files.

You can create a new task or a new step in a task using the commands "RelationalAI: New Task" and "RelationalAI: New Task Step", respectively. It will walk you through a series of prompts and insert a TOML entry that corresponds to the options you selected.

Running a task

To run a task, open the command palette and type RelationalAI: Run Task. You will be prompted to select a task file. The task will be run in the background, and you can view its progress in the Status Bar (along the bottom of the window).

Loading data

To load a CSV or JSON file, select RelationalAI: Load CSV or RelationalAI: Load JSON from the command palette (Ctrl+Shift+P, or Cmd+Shift+P on Mac).

Sending code to the server

In a .rel file or a .md file, you can select some text and invoke RelationalAI: Query from the command palette to send the text as a query. Alternatively, you can send a query with the shift+enter keyboard shortcut. If you want to send the whole file, do Ctrl+A to select all of the text before doing shift+enter.

To execute code in update or install mode, use the command palette to run RelationalAI: Update or RelationalAI: Install, respectively. If you install a model, the model name is determined by the file path of the open editor relative to the project root (the folder you have open in VS Code). For example, if you've opened ~/my-project/ and the file name is ~/my-project/model/profit.rel, then the model name will be model/profit.rel.

This code execution feature includes several conveniences:

1. You can place your cursor in a block of text and do shift+enter to automatically select the whole block. For this purpose, a block is delineated by blank lines.

2. If your submitted code starts with //update or // update, then it will be sent in update mode even if you used shift+enter instead of RelationalAI: Update. Likewise, if your submitted code starts with //install or // install, then it will be sent in install mode even if you used shift+enter instead of RelationalAI: Update.

3. If the document is in the Markdown language mode (for example, if it has an .md extension), then you can send an entire fenced code block like this:

   ```rel type=install&id=profit
   def profit[t] = revenue[t] - cost[t]
   ```
   

   Such a block will be run in install mode with the given id value used to identify the cell. The id can be omitted if the block is not an install block, and the type can be omitted if you want the cell to run as a query cell.

   Furthermore, you don't have to select the entire block to send it. You can put your cursor inside the code block and do shift+enter to run it.

If you want to send an entire folder's worth of .rel files to the cloud, you can use the command RelationalAI: Sync Folder to Cloud. Files that don't end in .rel will be ignored.

Outline view

If you click the top icon in the Activity Bar on the left side of the VS Code window, the sidebar will open to a view that includes an item called "OUTLINE". This shows you which relations are defined in the currently open editor. You can click on an item to navigate to it in your editor.

Autocomplete and hover support

When you start typing a relation name (in a .rel file), you will get autocomplete suggestions. The suggestions come from the standard library as well as the list of the base and derived relations defined in the currently selected database. Completion is also available for Unicode characters; see the Appendix below. You can view the docstring for any standard library relation by hovering over the name or by clicking the arrow on the right side of the autocomplete suggestion.

Configuration

Profiles and default databases and engines

If you have multiple profiles in ~/.rai/config, you can switch between them using the command RelationalAI: Set Profile or by clicking on the profile indicator in the status bar (the thin strip along the bottom of the window).

The selected profile, database, and engine for each project will be remembered by the extension and used when you re-open a project folder in VS Code. If you want to set defaults for these yourself, you can put them in a file named relationalai-vscode.toml in the root of your project. The file should look like this:

profile = "my_profile"
database = "my_database"
engine = "my_engine"

You can create this file using the command "RelationalAI: Configure. The command will show you the list of configuration options, prompt you for values, open your relationalai-vscode.toml (creating it if necessary) and insert an appropriate line in the TOML file.

In addition to the project-level configuration, you can create the file ~/.rai/relationalai-vscode.toml and use it to associate default settings for the profiles in ~/.rai/config.

The priority order for these settings is as follows:

1. Project configuration file.
2. User configuration file.
3. Settings used in this project the last time it was opened.
4. Settings used the last time you used the extension (any project).

Default directory names

If you prefer to use names other than model, update, and query to store your Rel files, you can configure the extension to use different names. To do this, put the following lines in the relationalai-vscode.toml file in the root of your project (or in ~/.rai):

model-directory = "my_model_dirname"
update-directory = "my_update_dirname"
query-directory = "my_query_dirname"

If you want to put these directories in a subdirectory of your project, use the following configuration:

rel-directory = "my_rel_dirname"

With the above settings, the extension would expect to find your model files in my_rel_dirname/my_model_dirname and your update files in my_rel_dirname/my_update_dirname.

Output caching

The extension can be configured to cache query output. This is useful if you want to go back and look at the output of a long-running query that you ran earlier. To enable this behavior, put the following line in the relationalai-vscode.toml file in the root of your project (or in ~/.rai):

cache-output = true

The outputs are cached in a folder called .rai in the root of your project. You can clear this cache at any time by deleting this folder.

If you are caching query results, then the alt+shift+enter (option+shift+enter on Mac) keyboard shortcut can be used the same as shift+enter except that it only hits the cache and does not send the query to the cloud. You will get an error message if no cache is available for the given query.

Model names

By default, a model with a name of profit will be stored in your local model directory with the name profit.rel. Similarly, if you create a local file called revenue.rel, it will be called revenue when sent to the cloud. In other words, the .rel file extension is added when copying a model from the cloud and removed when copying a model to the cloud.

If you want your models to have the same name in the cloud and local file system, you can put the following line in the relationalai-vscode.toml file in the root of your project (or in ~/.rai):

use-dot-rel-extension-in-model-name = true

With this setting, a local file called sales.rel will fsto the cloud as a model named sales.rel. Likewise, a model named employees will sync to the local file system as a file called employees (no extension).

Output inference

You can set the VS Code extension to automatically translate a query like this:

def R {
    1; 2; 3
}

into this:

def R {
    1; 2; 3
}

def output = R

This setting doesn't affect queries that contain multiple rules. To turn this settig on, put the following line in the relationalai-vscode.toml file in the root of your project (or in ~/.rai):

infer-output = true

Engine and database filters

If you want to limit the results that display in the engine and database output listings, you can do that with database-filter-regex and engine-filter-regex settings in your relationalai-vscode.toml file (or in ~/.rai):

database-filter-regex = "anon.*"
engine-filter-regex = "anon.*"

The settings above, for example, would show you only the databases and engines whose names start with anon.

This works by doing (new RegExp("^" + yourSetting)).test(engineName) in Javascript, so you can consult documentation for Javascript regular expressions for specific regex details for this feature.

User relationalai-vscode.toml file

If there are settings that you want to use for all of your projects, you can put them in a file called ~/.rai/relationalai-vscode.toml. Each setting is resolved by first consulting the project-level relationalai-vscode.toml file and then the user-level relationalai-vscode.toml file if that setting is not present in the project-level file.

Support

Note: This extension is the early stages of development and is currently being supported by a small team. Feedback is very much welcomed. We expect to address bug reports and will do our best with feature requests as well.

Appendix

There are also Unicode completions available: