Machine Learning

GQLDB can train and apply supervised machine-learning models inside the database, reusing built-in graph algorithms and embeddings as features. Pipelines and trained models are stored in the graph catalog and survive a database reopen.

Two tasks are supported:

• Node Classification: predict a class label for each node (e.g. churn, fraud, category).
• Link Prediction: predict missing or future edges (recommendations, knowledge-graph completion).

The Workflow

Both tasks follow the same four steps:

1. Create a pipeline: a named, persisted recipe (target + feature steps + split).
2. Add feature steps: existing node properties and/or graph algorithms (degree, PageRank, embeddings, etc.) whose per-node output becomes a feature.
3. Train: split the labeled data, fit a classifier, evaluate on a held-out test set, and persist the model.
4. Predict: score nodes (classification) or candidate node pairs (link prediction); stream or return the result (node classification can also write it back to a property).

The split (step 3) divides the labeled data into a training set (the rows the model learns from) and a held-out test set (rows kept aside to measure how well the model does on data it didn't train on). You can tune it with ml.configure_split, or rely on the default (20% held out for testing).

Models

Pass modelType to the train procedure:

• logistic_regression (default) params: learningRate, maxEpochs, penalty. Training is deterministic.
• random_forest params: numTrees, maxDepth, minSamplesLeaf, maxFeatures.

Add folds: <k> (≥2) to either to report a mean k-fold cross-validation score (cvScore) alongside the held-out metrics.

How Features and Prediction Work

• Feature matrix. Each feature step contributes columns built from a node property. A scalar property gives one column; a LIST property (e.g. an embedding) expands into one column per element. Missing values contribute 0. The column layout (the feature schema) is frozen into the model at train time.
• Standardization. Per-column mean/standard-deviation are computed on the train split only, stored on the model, and re-applied identically at prediction time; no leakage from the test split.
• Label encoding. Distinct values of the target property are sorted into class indices stored on the model.
• Frozen snapshot. A model keeps its own copy of the pipeline as it was at train time, so editing or dropping the pipeline afterward never invalidates the model — ml.drop_pipeline does not cascade to models.

Determinism and Stochastic Features

Logistic-regression training is deterministic. Some embedding algorithms (FastRP, Node2Vec) are stochastic, so they are materialized once at train time; prediction reuses the values written then rather than re-running them (which would change the embeddings and invalidate the model). To refresh embeddings, retrain.

Computing Engine

Algorithm feature steps run the corresponding built-in algorithm; topology-based algorithms are far faster with the computing engine enabled:

GQL
ALTER GRAPH social SET COMPUTE ENABLED

Feature materialization and prediction write-back use the incremental property-write path and never trigger a topology rebuild.

Procedures

Every operation is an ml.* procedure invoked with CALL. Two conventions apply throughout:

1. The name can be positional. The first parameter of every procedure is the pipeline (or model) name. You can pass it on its own before the options map, or as a key inside the map:

GQL
-- name positional
CALL ml.create_pipeline('roles', {
  targetLabel: 'User',
  targetProperty: 'role'
})

-- Equivalent: name as a map key
CALL ml.create_pipeline({
  name: 'roles',
  targetLabel: 'User',
  targetProperty: 'role'
})

1. mode chooses what a procedure does with its output. run (the default) returns the rows as a result table; stream emits them incrementally; write persists them back into the graph. Select a non-default mode either by suffixing the procedure name or by passing a mode option:

GQL
CALL ml.predict_nc.stream({model: 'role_model'})

-- Equivalent
CALL ml.predict_nc({model: 'role_model', mode: 'stream'})

Only the modes a procedure lists are valid (for example, ml.predict_lp supports run and stream, but not write).

ml.create_pipeline

Creates a pipeline: a named, persisted recipe of task + target + feature steps + split. Set task to choose node classification or link prediction; the task determines which of the target options apply.

Returns

ml.add_feature

Appends one feature step to a pipeline, either an existing node property, or an algorithm whose per-node output is materialized to a property at train time and then used as the feature. Provide either property or algo (with output). Call it once per feature.

Returns

ml.configure_split

Sets the train/test split applied at training time. The accuracy/f1 reported by train_nc/train_lp are computed on the held-out test set. Optional: a pipeline that is never configured uses the defaults below. The split is stratified (each class keeps its proportion in both the train and test sets).

Returns

ml.train_nc / ml.train_lp

Trains and persists a model from a pipeline: ml.train_nc for node classification, ml.train_lp for link prediction. Both share the same parameters; the only differences are that ml.train_lp defaults metric to AUC (with mean-AUC cross-validation), while ml.train_nc defaults metric to F1_WEIGHTED (with mean-accuracy cross-validation).

Returns

NOTE

Combiners for link prediction are set on the pipeline (create_pipeline), not on train_lp.

ml.predict_nc

Applies a trained node-classification model, scoring every node of the model's (frozen) target label.

In write mode (ml.predict_nc.write), a second map maps result columns to node properties: {db: {property: {predictedClass: 'pred', probability: 'pred_prob'}}}.

Returns (run / stream)

In write mode, returns task_id and nodesWritten instead.

ml.predict_lp

Applies a trained link-prediction model, scoring candidate non-adjacent, 2-hop node pairs and returning the most likely missing links. Unlike predict_nc, it has no write-back mode.

Returns

ml.list_pipelines / ml.list_models

Lists the pipelines or trained models in the current graph's catalog. No parameters.

Returns — ml.list_pipelines

Returns — ml.list_models

ml.drop_pipeline / ml.drop_model

Removes a pipeline or trained model from the catalog. Dropping a pipeline does not affect models already trained from it (each model holds a frozen snapshot).

Returns

Notes & Limitations

• Model weights are stored inline in the graph metadata. Logistic-regression blobs are tiny; random forests are larger (inline, with bounded defaults).
• Prediction reads features from the same properties written at train time — ensure those properties are present on the nodes you predict. For nodes added after training, re-run training (or materialize the feature) before predicting.