Using the Python SDK through Visual Studio Code

Learn how to set up a VSCode Environment for use with Python and RAI Cloud.

This guide describes how to set up a Microsoft VSCode environment to work with the RAI Python SDK. For more information on the Python SDK, see the RelationalAI SDK for Python

Prerequisites#

• Python. Check the Python RAI SDK for minimum version requirements.
• The Python RAI SDK.
• Visual Studio Code.

You can find useful information on working with Python in VSCode from the official VSCode website.

Creating a Configuration File for RAICloud#

In order to connect to RAICloud from VSCode, you need to create a configuration file with RAI Credentials: a client_id and a client_secret provided to you by a RAICloud administrator.

You should store this file according to the conventions of your operating system. In MacOS and Linux, for example, you will generally want to place this file in ~/.rai/config.

You will later indicate the location of the file when using the SDK.

For more information on OAuth clients, see Managing OAuth Clients.

Acquiring RAI Cloud Credentials#

To get RAI Cloud credentials, follow these steps:

1. Request an account from RAI.
2. Once the account is set up, an admin user is assigned to the account.
3. This admin uses the RAI Console to create OAuth Clients.
4. Each client is identified by a client_id and a client_secret key.

For information on sharing OAuth credentials, see Sharing OAuth Credentials.

Once you have a client_id and client_secret, you need to add these to your ~/.rai/config file.

The structure of this file is as follows:

[default]
# profile name, mandatory
host = azure.relationalai.com
port = 443
# optional, default: 443
scheme = https
# optional, default: https
client_id = ################
# from RAICloud admin
client_secret = ##############
# from RAICloud admin
client_credentials_url = https://login.relationalai.com/oauth/token  # optional
# default: https://login.relationalai.com/oauth/token

Here, [default] is the profile name. You will refer to this profile name when using the SDK.

You can specify more than one profile in addition to [default], such as [my-profile]. These should have the same attributes as above.

Installing Python#

Following instructions for your operating system, install Python. For the minimum required version, check the Python RAI SDK. You also need to install dev packages and pip. Note that these may be included with your Python installation.

Installing Visual Studio Code#

Install Visual Studio Code by following the instructions here.

Installing the Python Extension#

In order to begin using the Python SDK, you need to install and enable the Python extension in VSCode.

To install the Python extension:

1. Click View > Extensions.
2. Enter “Python” in the Search Box.
3. Under Python, click Install.

Once installed, you see something like this:

Installing the Rel Extension#

RelationalAI provides a Rel extension for VSCode. This extension highlights Rel syntax.

To install the Rel extension:

1. Click View > Extensions.
2. Enter “Rel” in the Search Box.
3. Under Rel, click Install.

Once installed, you see something like this:

Verifying the Python Installation#

Next, you need to verify that your Python installation is visible from within VSCode.

Open a new terminal window by selecting Terminal > New Terminal.

Depending on your Python installation, enter code along the following lines:

python3 --version

or

python3.7 --version

You should be using a version along the following lines:

Python 3.7.13

Installing the RAI SDK Package for Python#

Next, you need to install the RAI SDK package for your Python installation.

Depending on your installation, enter code along the following lines. Make sure that you are installing the RAI SDK for the correct version of Python (you may need to usepip3.7 if, for example, you have Python 3.7 installed).

pip3 install rai-sdk

You should see a message along the following lines:

Successfully installed ed25519-1.5 rai-sdk-0.6.3

At this point, you have successfully created a VSCode environment with Python and the RAI SDK for Python.

Writing Python for the RAI SDK#

You can now begin writing Python code that will execute against the RAI SDK.

Creating a Python File#

To create a Python file, follow the steps below:

1. Choose File > New File.
2. Enter “Python” in the dialog box that opens.
3. Click Python.

A new Python file opens.

5. Choose File > Save and save the file with a name such as myrel.py.

Testing Python#

Next, you can write some simple Python code to ensure things work properly.

First, make sure that the correct version of Python is selected in the Interpreter in the lower right-hand corner of VSCode:

Next, enter the following code into the Python file you created:

# this is a simple file
for i in range(3):
   print("Hello World")

Click the run triangle button in the top right-hand corner.

The following should return in the terminal in the bottom right of the VSCode editor:

Hello World
Hello World
Hello World

Creating a Simple Rel File#

To create a Rel file, follow the steps below:

1. Choose File > New File.
2. Click Enter or Return to create a new file.
3. In the file that opens, click Select a language.
4. Enter “Rel” in the Select language mode dialog box.
5. Click Rel.

A new Rel file opens.

You can now add some simple Rel code to the file:

def output[x in {1;2;3}] = 2*x

The file appears with Rel syntax highlighting:

6. Choose File > Save and save the file with a name such as simple.rel.

You can now read in this file from Python and send it over to RAICloud.

Connecting to a Database in RAICloud#

You can now write code that connects to a database and engine in RAICloud and issues a simple query. Both the database and engine need to have been added to RAICloud. For more information, see Managing Engines and Managing Databases.

The code below uses python-sdk-engine as the engine name and my-database for the database name.

To create the Python file:

1. Choose File > New File.
2. In the dialog box that opens, enter “Python” and select Python from the list.
3. Save the file in the same directory as the Rel file created above.
4. Enter the following code into the file:

import json

from pathlib import Path
from railib import api, config, show
from urllib.request import HTTPError

# read configuration
# you can use cfg = config.read() if both the file and the profile
# have the default values of ~/.rai/config and profile [default]
cfg = config.read("~/.rai/config", profile = "default")

# create a context
ctx = api.Context(**cfg)

# set the engine to connect to (must exist)
engine = "python-sdk-engine"

# set the database to connect to (must exist)
database = "my-database"

# read the Rel program from the simple.rel file
# (you may need to set the correct path of the file)
# and then issue a Rel query and get the results back
try:
    rel_code = Path("simple.rel").read_text()
    # rsp is a dict
    rsp = api.query(ctx, database, engine, rel_code)
except HTTPError as e:
    show.http_error(e)

# grab the resulting data and convert to row-wise format
data = rsp['output'][0]['columns']
rows = zip(*data)

# compute the squares
rows_squared = [ (i, v, v**2) for (i, v) in rows]

print(rows_squared)

5. Click the run triangle button in the top right-hand corner.

The following should return in the terminal in the bottom of the VSCode editor:

[(1, 2, 4), (2, 4, 16), (3, 6, 36)]

At this point, you are ready to begin using VSCode with the Python SDK.

Next Steps#

• Using the RelationalAI SDK for Python
• The Rel Primer