ML Pipelines
Train and run graph machine-learning models entirely from Cypher. Traverse 0.8.0 ships node-classification pipelines with GNN model candidates (GCN, GraphSAGE), asynchronous training on GPU or CPU, a model catalog with .tvmodel persistence, and in-browser inference. The underlying ML engine also implements R-GCN, GAT, GraphMAE pretraining, and node-regression / link-prediction heads, which surface in future pipeline releases.
Workflow
The procedure namespace mirrors the GDS pipeline shape: create a pipeline, configure features and model candidates, train against a graph projection, then predict.
-- 1. Create a pipeline
CALL traverse.ml.pipeline.nodeClassification.create('churn');
-- 2. (Optional) derive node features with any GDS algorithm
CALL traverse.ml.pipeline.nodeClassification.addNodeProperty('churn',
'traverse.fastRP', {embeddingDimension: 64, mutateProperty: 'embedding'});
-- 3. Select which properties feed the model
CALL traverse.ml.pipeline.nodeClassification.selectFeatures('churn', ['embedding', 'age']);
-- 4. Add model candidates
CALL traverse.ml.pipeline.nodeClassification.addGcn('churn', {hidden: 32});
CALL traverse.ml.pipeline.nodeClassification.addGraphSage('churn', {hidden: 64});
-- 5. Train (asynchronous - returns a job id immediately)
CALL traverse.ml.pipeline.nodeClassification.train('my-graph', {
pipeline: 'churn',
targetProperty: 'churned',
modelName: 'churn-v1',
epochs: 200,
learningRate: 0.01
}) YIELD jobId, status;
-- 6. Poll training progress
CALL traverse.ml.pipeline.nodeClassification.trainStatus($jobId)
YIELD status, elapsedSeconds, modelInfo, modelSelectionStats;
-- 7. Predict - stream results or write them back
CALL traverse.ml.pipeline.nodeClassification.predict.stream('my-graph', {modelName: 'churn-v1'})
YIELD nodeId, predictedClass, predictedProbabilities;
CALL traverse.ml.pipeline.nodeClassification.predict.write('my-graph', {
modelName: 'churn-v1', writeProperty: 'churn_predicted'
}) YIELD nodesWritten, writeProperty;Procedure reference
Pipeline configuration
| Procedure | Arguments |
|---|---|
...nodeClassification.create | pipelineName |
...addNodeProperty | pipelineName, procedureName, configuration - run a GDS algorithm as a feature step |
...selectFeatures | pipelineName, nodeProperties (string or list) |
...configureSplit | pipelineName, configuration - train/test split settings |
...configureAutoTuning | pipelineName, configuration - hyperparameter search budget |
...addGcn / ...addGraphSage | pipelineName, configuration (e.g. {hidden: 32}) - add a GNN candidate |
...removeCandidate | pipelineName, candidateIndex |
traverse.ml.pipeline.list | - lists pipelines with candidate/feature counts |
traverse.ml.pipeline.drop | pipelineName |
All configuration procedures return the pipeline state: name, nodePropertySteps, featureProperties, splitConfig, autoTuningConfig, parameterSpace.
Training and prediction
| Procedure | Notes |
|---|---|
...train(graphName, config) | Asynchronous. Config: pipeline, targetProperty, modelName, epochs (default 100), learningRate (default 0.01). Yields jobId, status immediately. |
...trainStatus(jobId) | Yields status, elapsedSeconds, trainMillis, modelInfo, modelSelectionStats, error |
...predict.stream(graphName, config) | Yields nodeId, predictedClass, predictedProbabilities |
...predict.write(graphName, config) | Config: modelName, writeProperty, overwriteExisting. Yields nodesWritten, nodesSkipped, writeProperty |
...targetCandidates() | Surveys properties usable as training targets |
Model catalog
| Procedure | Notes |
|---|---|
traverse.ml.model.list() | Name, target, architecture, pipeline, accuracy, class labels, metrics per trained model |
traverse.ml.model.drop(modelName) | Removes the model (and its .tvmodel file) |
traverse.ml.model.setMetadata(modelName, key, value) | Attach metadata; re-persists the model |
traverse.ml.model.export(modelName) | Yields the model as base64 .tvmodel bytes for transport |
Model persistence
Trained models persist as <modelName>.tvmodel files in the same directory as your .tvdb databases (TRAVERSE_DATA) and are re-loaded on startup. The HTTP file APIs accept ?kind=model for uploading and downloading model files.
Studio
Studio's ML Pipelines panel wraps this whole lifecycle in a UI: a train wizard (pick target, features, candidates), live training progress, metric inspection, one-click prediction with write-back, and model file management.
Inference in the browser
The companion @truespar/traverse-ml-wasm npm package runs predictions in a browser tab: train server-side, ship the .tvmodel bytes (HTTP fetch or traverse.ml.model.export), and predict client-side on CPU (≈10 MB artifact) or WebGPU (≈30 MB). Training itself is server-only.
Build requirements
ML procedures require a server built with the ml feature - on in all official 0.8.0 release binaries and the Docker image (check features.ml in GET /api/health). Training runs on CUDA when available, with CPU fallback. Pipeline configuration procedures work even without the feature; train returns a clear "not built with ml" error.