Foreign Procedures in Kuneiform

Foreign procedures are a way to define an interface for interacting with procedures in another database. Foreign procedures can define an expected input and output, and specify the database and procedure that matches the interface. The target database can be set dynamically during runtime, allowing for dynamic procedure calls across databases.

database social_network;

// get_user is capable of calling a procedure in any other database on the network
// that takes a uuid and returns a text and an int
foreign procedure get_user($id uuid) returns (text, int)

// get_users is capable of calling a procedure in any other database on the network
// that takes no arguments and returns a table with columns username and age
foreign procedure get_users() returns table(username text, age int)

Calling Foreign Procedures

Foreign procedures are called like any other function/procedure. The only difference is that the target database id (dbid) and procedure name must be passed using square brackets:

foreign procedure get_user($id uuid) returns (text, int)

procedure call_get_user($id uuid) public  {
    $username, $age = get_user['x_target_dbid', 'target_procedure']($id);
    // $username is a text and $age is an int
}

Since the target procedure name is passed as a string, it is only necessary that the arguments and returns match the expected types. The underlying procedure being called can have any name, as long as the types match. For example, assume we have the following procedure in another database:

// dbid: xc2bc33cd97f0a811ced54f9b74b6cc2d375640909ddc513d5adac036
database math;

procedure add($a int, $b int) public view returns (sum int) {
    return $a + $b;
}

procedure subtract($a int, $b int) public view returns (difference int) {
    return $a - $b;
}

We can call the add and subtract procedures from the social_network database like so:

database social_network;

foreign procedure do_math($a int, $b int) returns (int)

procedure call_do_math($a int, $b int) public {
    $sum := do_math['xc2bc33cd97f0a811ced54f9b74b6cc2d375640909ddc513d5adac036', 'add']($a, $b);
    $dif := do_math['xc2bc33cd97f0a811ced54f9b74b6cc2d375640909ddc513d5adac036', 'subtract']($a, $b);
}

Dynamic Selection

The target dbid and procedure can also be passed as variables to the foreign procedure. This allows for dynamic selection of the target database and procedure at runtime:

database social_network;

foreign procedure do_math($a int, $b int) returns (int)

procedure call_do_math($target_proc text) public {
    $dbid := 'xc2bc33cd97f0a811ced54f9b74b6cc2d375640909ddc513d5adac036';
    $result := do_math[$dbid, $target_proc]($a, $b);
} 

Returning Tables

Similar to normal procedures, foreign procedures can return tables. The table column names must be specified, and the types must match the expected return types:

database social_network;

foreign procedure get_users() returns table(username text, age int)

procedure call_get_users() public returns table(username text) {
    return select username from get_users['x_target_dbid', 'target_procedure']();
}