CartoBoost GraphSAGE Models

Use GraphSAGE when node attributes should shape the graph representation. The graph is homogeneous: one node type and one edge type, with numeric features on each node.

When To Use

• Nodes have useful attributes at prediction time.
• Neighbor aggregation should smooth or transfer signal across connected nodes.
• You want a graph regressor or link predictor over a homogeneous graph.
• A graph-free tabular baseline is part of the comparison.

Interactive Example

GraphSAGE browser model

Runs graphsage in the browser with the bundled CartoBoost Wasm model.

Ready to run in this page.

Python Example

Regressor

import numpy as np
from cartoboost.graph import GraphSageStandaloneRegressor

edges = [(0, 1), (1, 2), (2, 3), (3, 0), (0, 2)]
source = np.array([0, 1, 2, 3], dtype=np.uint64)
target = np.array([1, 2, 3, 0], dtype=np.uint64)
dense = np.array([[4.2, 8], [2.0, 9], [7.1, 17], [3.5, 22]], dtype=float)
y = np.array([2.1, 1.6, 2.8, 1.9])
node_features = np.array(
    [[1.0, 0.0], [0.0, 1.0], [0.6, 0.3], [0.2, 0.7]],
    dtype=np.float32,
)

model = GraphSageStandaloneRegressor(input_dim=2, hidden_dims=(8,), epochs=2)
model.fit(
    node_features=node_features,
    edges=edges,
    row_nodes=source,
    row_targets=target,
    dense=dense,
    y=y,
)

pred = model.predict(
    node_features=node_features,
    row_nodes=source,
    row_targets=target,
    dense=dense,
)

Link Predictor

from cartoboost.graph import GraphSageLinkPredictor

predictor = GraphSageLinkPredictor(input_dim=2, hidden_dims=(8,), epochs=2)
predictor.fit(node_features=node_features, edges=edges)
scores = predictor.predict_scores(
    node_features=node_features,
    pairs=[(0, 1), (0, 3), (3, 2)],
)

Use When

Need	Better first choice
Node attributes matter in a homogeneous graph.	GraphSageStandaloneRegressor or GraphSageLinkPredictor
Only topology is available.	Node2Vec
Relation ids matter.	HeteroGraphSAGE
Node types and relation triples matter.	HinSAGE

Compute Backend

GraphSageConfig and GraphSageFeatureEncoder.from_config(...) default to backend="cpu" and also accept backend="auto" as a CPU-resolving alias, or an installed accelerated backend such as "metal", "rocm", or "cuda". On Apple-platform builds with native Metal support, Metal routes the dense GraphSAGE forward layers through the shared native backend kernel. On Linux or WSL builds with ROCm support compiled in, ROCm routes the same dense GraphSAGE forward layers through the shared HIP backend. On Windows or Linux builds with CUDA support, CUDA routes the same dense GraphSAGE forward layers through the shared CUDA backend. Neighbor aggregation and training backpropagation remain CPU work.

Validation

GraphSAGE can overstate quality when node attributes are computed with validation labels or future rows. Keep node features train-side for deployment claims, and report whether cold nodes appear in the holdout.

Limitations

• Neighbor sampling and feature construction can leak future graph state.
• Cold-node quality depends on usable node attributes and observed neighbors.
• Accelerator support covers documented kernels only; aggregation and training may remain on CPU.