Installing Models

This Concept Guide introduces the concept of an 'installed Rel source', which can be reused later in queries or as a building block for modeling.

Download this guide as a RAI notebook by clicking here.

Introduction

RAI databases are collections of (1) relational data and (2) definitions and rules that define a model that operates on that data.

In Rel, simple definitions are often expressed as part of the query, and forgotten afterwards. For example, this query computes the sum of the numbers from 1 to 10, putting them in a myrange relation and then asking for sum[myrange]:

query
def myrange(x) = range(1, 10, 1, x)

def output = sum[myrange]

Relation: output

55

The relation myrange is an IDB relation. When this query is issued from a “query” console notebook cell (or with a RelationalAI.query API call, for example), it is not persisted in the database, and its definition is forgotten once the query is finished. This query is read-only, and does not change the state of the database. (See the Updating Data: Working with EDB Relations concept guide for queries that update data.)

This is convenient for simple auxiliary relations that are only used once. In practice, however, and for more advanced Knowledge Graph Management System (KGMS) applications in particular, we will want to install definitions and models. This persists them as part of the database, to be reused later in queries, or as building blocks for other models. We call these installed Rel models or installed sources. In this way, a complex KGMS can be constructed in a modular way, as a collection of Rel libraries.

Installed Rel models are keyed by a user-defined name. They can be added, removed, or updated, as we will see below.

Simple Example

Let’s install a small Rel model source that defines the transformation from Cartesian to spherical coordinates. For a more mathematical look, we also define a (singleton) relation $\pi$ that holds the value of pi, taking advantage of Rel’s support for UTF-8 characters:

install
def π = pi_float64

@inline
def cartesian2spherical[XY] =
sqrt[x^2 + y^2], atan2[y, x] / π * 180
from x, y where XY(x, y)

Now that we have installed this definition in the database, we can use it in a query:

query
def xy = {("a", 2, 0); ("b", 0, 4); ("c", -9, 0); ("d", 1, -1)}
def r_phi[i] = cartesian2spherical[xy[i]]

def output = r_phi

Relation: output

"a"2.00.0
"b"4.090.0
"c"9.0180.0
"d"1.4142135623730951-45.0

Installed Model Sources and Integrity Constraints

If installing a source would cause an Integrity Constraint violation, the transaction will abort and the installation will fail. For example, we can install a definition together with a valid integrity constraint:

install
def myrel = {1; 3; 5}
ic myrel_odd(x) {
myrel(x) implies (x % 2) = 1
}

The integrity constraint passes (everything in myrel is odd), and both the IC and the definition are successfuly installed.

query
myrel

Relation: output

1
3
5

If we now try to include even numbers in myrel, the system notes that the myrel_odd IC would be violated. The install fails, and the definition for myrel will not change.

failed install
def myrel = {2; 4; 7}
def another_rel = pop_standard_deviation[myrel]

Any other definition in this same block of code, such as another_rel above, will not be installed either — the entire block will fail. We can check that myrel has not changed:

query
myrel

Relation: output

1
3
5

Queries that use (temporary) definitions that violate installed ICs will also fail — the example above will fail both as a query, and as an attempt to install an update to the myrel definition.

See the Integrity Constraints concept guide for more on ICs.

Note: if we don’t want to commit to specific values in myrel, we can initially install this instead:

def myrel = {}
ic myrel_odd(x) {
myrel(x) implies (x % 2) = 1
}

The def myrel = {} makes sure that myrel is not undefined, but still allows values to be added to it later, since defs for the same relation are unioned.

RAI Notebooks

Cells in a Rel notebook can simply be marked as query or install cells, to distinguish the two cases. Install cells are given a unique system-generated ID. See Guide to Working with RAI Notebooks for more details.

Normal query cells are read-only transactions. Cells marked as update cells can change EDB relations, but don’t install new sources. See the concept guide on Updating Data: Working with EDB Relations for more details.