The RelationalAI Predictive Reasoner

Learn how to use the RelationalAI Predictive Reasoner to produce meaningful predictions and embeddings from your relational data, supporting decision-intelligence tasks like identifying potential churn, detecting fraud, and more. The Predictive Reasoner helps you turn data into actionable insight.

Prerequisites

Before using the RelationalAI Predictive Reasoner, ensure the following requirements are met.

1. Snowflake Permissions for Experiment Tracking and Model Storage

To enable the RelationalAI application to save trained models, track experiments, and persist results, you must grant it access to a database and schema of your choice. These should match the database and schema specified in your ExperimentConfig.

The database and schema used for experiment tracking and model storage must be dedicated to RelationalAI artifacts only. Do not store other data in the same database or schema used for experiment tracking. Mixing user or application data with experiment tracking data can introduce security and operational risks and is not supported. We strongly recommend creating a separate database and schema specifically for experiment tracking and model storage.

Run the following commands in Snowflake (replace placeholders as needed):

-- Grant access to required database and schema
GRANT USAGE ON DATABASE <DATABASE> TO APPLICATION RELATIONALAI;
GRANT USAGE ON SCHEMA <DATABASE>.<SCHEMA> TO APPLICATION RELATIONALAI;
-- Allow storing experiment results
GRANT CREATE EXPERIMENT ON SCHEMA <DATABASE>.<SCHEMA> TO APPLICATION RELATIONALAI;
-- Allow registering trained models
GRANT CREATE MODEL ON SCHEMA <DATABASE>.<SCHEMA> TO APPLICATION RELATIONALAI;

2. Snowflake Role with Data Read and Write Access

The Snowflake role used when creating the Provider must have sufficient privileges to:

• Read input tables from the source database.
• Write prediction outputs back to the target database or schema.

Resources

• You can run the Predictive Reasoner Python SDK either locally or within a Snowflake notebook:
  • Start in Snowflake follow this guide.
  • Setup locally follow this guide.
• To prepare the dataset used in this tutorial follow this guide.
• Additional examples and use cases demonstrating how to use the Predictive Reasoner are available in the Examples section as well as in our GitHub repository of tutorials.

Create a Provider and a SnowflakeConnector

Use your snowflake credentials to create a Provider. The Provider supports multiple authentication methods, with examples available here. The following example demonstrates password-based authentication locally and active_session authentication in a Snowflake notebook.

Local

from relationalai_predictive import Provider

snowflake_config = {
    "user": "<SNOWFLAKE_USER>",
    "password": "<SNOWFLAKE_PASSWORD>",
    "account": "<SNOWFLAKE_ACCOUNT>",
    "role":"<SNOWFLAKE_ROLE_WITH_ACCESS_TO_DB>",
    "warehouse": "<SNOWFLAKE_WAREHOUSE>",
    "app_name": "RELATIONALAI",
    "auth_method": "password"
}
provider = Provider(**snowflake_config)

Snowflake Notebook

from relationalai_predictive import Provider

snowflake_config = {
    "app_name": "RELATIONALAI",
    "auth_method": "active_session",
    "role": "<SNOWFLAKE_ROLE_WITH_ACCESS_TO_DB>"
}
provider = Provider(**snowflake_config)

To get your account name, run the following command in Snowflake:

SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME();

To find the RelationalAI application name, list all applications with:

SHOW APPLICATIONS;

Use the provider to create a new reasoner under the name "<GNN_REASONER>":

provider.create_gnn(
    name="<GNN_REASONER>",
    size="HIGHMEM_X64_S"
)

Available compute pool sizes are listed in create_gnn() method documentation.

Created reasoners are automatically suspended after a period of inactivity, with a default autosuspension time of 1 hour. To modify this setting, see the create_gnn() documentation. To resume a suspended reasoner, refer to the resume_gnn() method.

The Provider can also be used to monitor reasoner status, delete unwanted reasoners, or list all available reasoners. See Provider for usage examples.

⚠️ Important Note: When configuring Provider, specify a role that has the required read and write access to databases you plan to use.

Use the same snowflake credentials and the reasoner name to create a SnowflakeConnector.

from relationalai_predictive import SnowflakeConnector

connector = SnowflakeConnector(
    **snowflake_config,
    engine_name = "<GNN_REASONER>"
)

Create a RelationalTable from a Snowfake Table

Once you have a SnowflakeConnector, you can construct a RelationalDataset consisting of two or more RelationalTables and a RelationalTask.

A RelationalTable can only be created from a Snowfake table using its fully-qualified name, e.g. <db>.<schema>.<table>, as shown below:

from relationalai_predictive import RelationalTable, ForeignKey, CandidateKey

# The name parameter specifies a custom name for the table, chosen by the user.
# Create a RelationalTable from 'STUDENTS' table from 'SYNTH_DB.SYNTH_SCHEMA' schema in Snowflake
student_table = RelationalTable(
    connector=connector,
    name="Students", # RelationalTable is uniquely identified by this name.
    source="SYNTH_DB.SYNTH_SCHEMA.STUDENTS",
    type="node",
    candidate_keys=[CandidateKey(column_name="studentId")],
)

# Create a RelationalTable from 'CLASSES' table from 'SYNTH_DB.SYNTH_SCHEMA' schema in Snowflake
class_table = RelationalTable(
    connector=connector,
    name="Classes", # RelationalTable is uniquely identified by this name.
    source="SYNTH_DB.SYNTH_SCHEMA.CLASSES",
    type="node",
    candidate_keys=[CandidateKey(column_name="classId")],
)

# Create a RelationalTable from 'STUDENT_TAKES_CLASS' table from 'SYNTH_DB.SYNTH_SCHEMA' schema in Snowflake
# Add two foreign keys:
# One referencing Students.studentId,
# where Students is the name of "SYNTH_DB.SYNTH_SCHEMA.STUDENTS" table defined above,
# and studentId is its candidate key column.
# One referencing Classes.classId,
# where Classes is the name of "SYNTH_DB.SYNTH_SCHEMA.CLASSES" table defined above,
# and classId is its candidate key column.
student_takes_class_table = RelationalTable(
    connector=connector,
    name="StudentsTakeClass", # RelationalTable is uniquely identified by this name.
    source="SYNTH_DB.SYNTH_SCHEMA.STUDENT_TAKES_CLASS",
    type="node",
    foreign_keys=[ForeignKey(column_name="studentId", link_to="Students.studentId"),
                  ForeignKey(column_name="classId", link_to="Classes.classId")]
)

In this example, we construct three RelationalTable objects of type node, meaning that each row in the table corresponds to a node in the graph. We also support RelationalTable objects of type edge, where each row defines an edge connecting two node instances. For more details, refer to RelationalTable documentation and see a practical example in Smoker Prediction with Edge List.

Notice that both student_table and class_table are constructed using candidate_keys argument, while student_takes_class_table uses foreign_keys argument. Here is a quick summary of rules for creating a RelationalTable object of type node. For more details, consult RelationalTable.

Note

• A RelationalTable must have at least one candidate key or foreign key.
• A RelationalTable cannnot have more than one time column.
• A RelationalTable can have any number of candidate keys (CandidateKey).
• A RelationalTable can have any number of foreign keys (ForeignKey).

Note

Table names and column names are case-sensitive and must comply with Snowflake object identifier rules. Always reference them exactly as they appear in Snowflake.

You have now converted three source tables from your Snowflake database into RelationalTables. All columns from source tables are included, and semantic types of all columns are automatically inferred from their data types. A full description of all supported data types can be found in Column DTypes. Since this inference is automatic, we recommend using .show_table() method to review inferred semantic types.

student_table.show_table()

When changes are needed, a suite of methods is available to modify your RelationalTable. See RelationalTable for more details on the methods. Below are some examples of changes you can make.

from relationalai_predictive import ColumnDType

# Do not use this column as an input feature for the RelationalTable
student_table.remove_column(col_name="participation")

# Change column semantic type, i.e. dtype
class_table.update_column_dtype(col_name="credits", dtype=ColumnDType('category'))

Finally, it’s recommended to use .validate_table() method to check for any inconsistencies in your RelationalTables before proceeding to the next step.

# Validate table
student_takes_class_table.validate_table()

Define a learning task

We support two broad types of learning tasks: NodeTask and LinkTask. For details please consult RelationalTask API.

The following example defines a NodeTask for binary classification. You will need to prepare three tables with class labels:

• SYNTH_DB.SYNTH_RANK.TRAIN
• SYNTH_DB.SYNTH_RANK.VALIDATION
• SYNTH_DB.SYNTH_RANK.TEST

All three tables should use the same schema. Each table must include:

• A studentId column that serves as a foreign key referencing studentId candidate key of RelationalTable with the nameStudents.
• A label column containing the binary label that the model is trying to predict. Note that the test table, SYNTH_DB.SYNTH_RANK.TEST, does not need to have a label column.

from relationalai_predictive import NodeTask, TaskType, ForeignKey

node_task = NodeTask(
    connector=connector,
    name="my_node_task",
    train_table="SYNTH_DB.SYNTH_RANK.TRAIN",
    validation_table="SYNTH_DB.SYNTH_RANK.VALIDATION",
    test_table="SYNTH_DB.SYNTH_RANK.TEST",
    target_entity_column=ForeignKey(column_name="studentId", link_to="Students.studentId"),
    label_column="label",
    task_type=TaskType.BINARY_CLASSIFICATION
)

Similarly, you can use the .show_task() method to review settings of the NodeTask. For instructions on modifying these default settings, please consult the RelationalTask API.

node_task.show_task()

Compose a RelationalDataset from RelationalTables and a RelationalTask

Using the defined RelationalTable objects, the NodeTask and the SnowflakeConnector, you can construct a RelationalDataset as follows:

from relationalai_predictive import RelationalDataset

dataset = RelationalDataset(
    connector=connector,
    dataset_name="my_first_dataset",
    tables=[student_table, class_table, student_takes_class_table],
    task_description=node_task
)

The .visualize_dataset() method is provided to help you inspect the connectivity between all your tables and the task. For more details, please consult RelationalDataset API.

Local

dataset.visualize_dataset().display()

Snowflake Notebook

import streamlit as st

diagram = dataset.visualize_dataset()
st.image(diagram._render("png"))

Train a model and generate predictions

Once your RelationalDataset is ready, you can proceed to train a model. To do this, you need to define three additional objects as shown in the example below:

from relationalai_predictive import ExperimentConfig, GNNConfig, GNNEstimator

experiment_config = ExperimentConfig(database="database_name",
                                     schema="schema_name")

gnn_config = GNNConfig(connector=connector,
                       experiment_config=experiment_config,
                       device="cuda",
                       n_epochs=10)

estimator = GNNEstimator(connector=connector, config=gnn_config)

train_job = estimator.fit(dataset=dataset)

ExperimentConfig specifies the database and schema where the experiment results, such as model metrics, will be stored.

GNNConfig contains all training parameters. In the example, default values are used for all parameters. For a comprehensive list of training parameters and examples of modifying their values, see GNNConfig API.

The other object you will need is GNNEstimator, which is simply defined using a SnowflakeConnector and a GNNConfig object. Finally, to train a model, use .fit() method and pass in your prepared RelationalDataset. For more information on GNNEstimator and its methods, refer to GNNEstimator API.

Note

• Model training are non-blocking jobs. In other words, .fit() method returns a JobMonitor object, which you can use to track the progress of the job while it runs in the background. For details on monitoring jobs, see the JobMonitor API.
• Ensure the native app has the necessary permissions to the database and schema specified in ExperimentConfig.

-- grant access to resources needed for snowflake experiment tracking

GRANT USAGE ON DATABASE <DATABASE> TO APPLICATION RELATIONALAI;
GRANT USAGE ON SCHEMA <DATABASE>.<SCHEMA> TO APPLICATION RELATIONALAI;
-- grant access to store experiment results
GRANT CREATE EXPERIMENT ON SCHEMA <DATABASE>.<SCHEMA> TO APPLICATION RELATIONALAI;
-- grant access to register models
GRANT CREATE MODEL ON SCHEMA <DATABASE>.<SCHEMA> TO APPLICATION RELATIONALAI;

Once a model is trained, you can generate batch predictions using .predict() method of GNNEstimator object.

from relationalai_predictive import OutputConfig

inference_job = estimator.predict(
    output_alias="experiment_1",
    output_config=OutputConfig.snowflake(
        database_name="SYNTH_DB",
        schema_name="PUBLIC"
    ),
    dataset=dataset,
    model_run_id=train_job.model_run_id,
)

In this example, predictions will be saved to PREDICTIONS_EXPERIMENT_1 table in SYNTH_DB.PUBLIC schema in Snowflake. Please make sure that your Snowflake role, used in SnowflakeConnector, has write permissions for this schema. For more details on .fit() and .predict() methods, see GNNEstimator API.

To manage all jobs you have created in a session, we also provide JobManager class. For more details, please refer to JobManager API.

Zero-shot predictions with ICLEstimator

If you don’t want to train a model at all, the SDK also provides ICLEstimator: zero-shot in-context learning (ICL) inference. Instead of training on a train_table and registering a model, you provide a context table of already-labeled examples, and ICLEstimator uses it directly as context at inference time — there is no training loop and no model artifact to manage.

Use ICLEstimator when you want predictions quickly and don’t have (or don’t want to spend time building) a large labeled training set, or when you want a fast baseline to compare against a trained GNNEstimator model. Use GNNEstimator/GNN training instead when you have a substantial labeled dataset and want the best achievable accuracy, since a trained model generally outperforms zero-shot ICL given enough data.

ICLEstimator works with the same multi-table RelationalDataset/RelationalTask objects used for GNN training, or with a single flat table via TabularTask/TabularDataset — the latter also supports forecasting tasks. See the ICLEstimator API for details.