Installation

Install RBC and get started

You can install RBC using conda (recommended) or mamba, which is a faster implementation of conda. For more information, see the Mamba documentation.

conda install -c conda-forge rbc

# or to install rbc to a new environemnt, run
conda create -n rbc -c conda-forge rbc
conda activate rbc

# check if rbc installed succesfully
python -c 'import rbc; print(rbc.__version__)'

You can also use pip for package management:

pip install rbc-project
# check if rbc installed succesfully
python -c 'import rbc; print(rbc.__version__)'

Quick Start

The following assumes that you have an instance of HEAVY.AI running. UDFs and UDTFs are enabled with the flags --enable-runtime-udfs and --enable-table-functions. For more information on installing HEAVY.AI, see Installation.

To summarize:

conda create -n heavy-ai-env heavydb -c conda-forge
conda activate heavy-ai-env
mkdir -p data
initheavy data -f
heavydb --enable-runtime-udfs --enable-table-functions

To inspect the test database—provided by default—connect another terminal to the database using

heavysql --passwd HyperInteractive

The following example shows a simple UDF that converts a numerical temperature from Fahrenheit to Celsius. The code defines the function, registers it, and runs it on the server.

from rbc.heavydb import RemoteHeavyDB

heavy = RemoteHeavyDB(
    user='admin',
    password='HyperInteractive',
    host='localhost',
    port=6274,
    dbname='heavyai',
)

@heavy('double(double)')
def fahrenheit2celsius(f):
    return (f - 32) * 5 / 9

print(fahrenheit2celsius(32))
# 'fahrenheit2celsius(CAST(32 AS DOUBLE))'

# other functions?
...

# after defining all functions, they should be registered
# to the database
heavy.register()

The instance of class RemoteHeavyDB connects to the HeavyDB instance, and the object it returns can be used to register functions. Then, you define a normal Python function fahrenheit2celsius. The function is decorated using the instance heavy of the class RemoteHeavyDB, and it is provided with the function signature 'double(double)'. With this modification, the decorated function expects a single argument that is a double-precision floating-point value and also returns a double-precision floating-point value. The syntax is similar to function annotations in C/C++.

After you defined all functions you want to be available on the HeavyDB server, you should register them all at once with heavy.register().

fahrenheit2celsius can now be used in SQL on the HeavyDB server. You can use tools like heavyai or ibis (via the ibis-heavyai backend) to help construct queries from Python. The following example shows a function call from SQL.

SELECT fahrenheit2celsius(col) FROM my_table

The function is then applied element-wise on the column col of the table my_table.