Understand GNN workflows

A GNN instance runs in one of two workflows:

• A fit workflow trains a new model on labeled splits, then predicts (and optionally registers the trained model).
• A load workflow retrieves an already-trained model, then predicts.

The workflow is implicit — PyRel determines which one a GNN is in from the constructor arguments. If you pass training fields (train, validation), you’re in the fit workflow. If you pass a model identifier (model_run_id or the registry parameters model_database / model_schema / model_name / version_name), you’re in the load workflow. Mixing arguments from both workflows raises an error at construction time.

Once the workflow is fixed, only certain method-call sequences are valid. The rest of this page enumerates them.

Use the fit workflow

Construct the GNN with training arguments, call fit() to train, then call predictions() on the test domain. You can optionally call register_model() at the end to save the trained model to the Snowflake Model Registry:

gnn = GNN(
    exp_database=...,
    exp_schema=...,
    graph=gnn_graph,
    property_transformer=pt,
    train=Train,
    validation=Validation,
    task_type=...,
    eval_metric=...,
)
gnn.fit()
gnn.score()   # optional — evaluation metrics for the validation split
Source.predictions = gnn.predictions(domain=Test)
gnn.register_model(...)   # optional

See Configure and train a GNN for the full set of fit-workflow arguments.

Use the load workflow

Construct the GNN with a model identifier, call load() to retrieve the trained model, then call predictions():

gnn = GNN(
    exp_database=...,
    exp_schema=...,
    graph=gnn_graph,
    property_transformer=pt,
    source_concept=SourceConcept,
    task_type=...,
    has_time_column=...,
    model_run_id="<model_run_id>",   # or the four registry parameters
)
gnn.load()
gnn.score(domain=LabeledSplit)   # optional — needs a labeled split, unlike predictions()
gnn.register_model(...) # optional, only possible if pretrained model is loaded via model_run_id
Source.predictions = gnn.predictions(domain=Test)

See Use a pretrained model for the full set of load-workflow arguments.

Score a fitted or loaded model

score() evaluates a GNN against a labeled split and returns the resulting metrics — pass domain= explicitly, or omit it to score against the validation split from the constructor:

gnn.fit()
metrics = gnn.score()          # scores against `validation`
metrics = gnn.score(domain=OtherLabeledSplit)   # or against any other labeled split

Unlike predictions(), whose test domain carries no label column, score()’s domain must have the same shape as train/validation — source concept plus label column. score() requires graph to have been provided at construction, in both the fit and load workflows, since it re-derives features the same way fit() did.

Invalid workflows

The following call sequences raise errors:

• Calling fit() in a load workflow. Once a GNN is constructed with load arguments, gnn.fit() raises an error. To train, construct a separate fit-mode GNN instance.
• Calling load() in a fit workflow. Once a GNN is constructed with training arguments, gnn.load() raises an error. To load a previously trained model, construct a separate load-mode GNN instance.
• Re-registering a model loaded from the registry. If a GNN was loaded by model_database / model_schema / model_name / version_name, calling gnn.register_model(...) raises an error — that model is already registered under those parameters. To register a different version, train and register a fresh model.
• Calling predictions() before fit() (or load()). A GNN can only predict on a test domain after it has been fitted (fit workflow) or loaded (load workflow). Calling gnn.predictions(...) before either raises an error.
• Calling score() before fit() (or load()). Same requirement as predictions() — the model must be fitted or loaded first.
• Calling score() without graph, and without a labeled domain. score() requires graph to have been provided at construction. It also needs a labeled domain — pass domain= explicitly, or construct the GNN with validation=... so score() can be called with no arguments.
• Calling register_model() before fit(). A model must be trained before it can be registered. Calling gnn.register_model(...) before gnn.fit() raises “Model is not fitted. Call gnn.fit() first.”
• Calling register_model() twice on the same GNN instance. Once a GNN has been registered, it cannot be registered again — even under a different name or version. To register another version, train a fresh model and register that.

The following call sequence has no effect:

• Calling fit() twice on the same GNN instance. A GNN can be trained at most once; the second fit() call produces a warning and has no effect. To retrain with different hyperparameters, construct a new GNN instance.