Random Forest Classifier
UDTF: cuml_random_forest_classifier
Official cuML reference: Python API
Fit a query-local cuML random forest classifier and score independent rows.
Quickstart
Register the relations referenced by the parenthesized SELECT clauses below. For metadata validation, the descriptor names training_vectors and predict_vectors.
SELECT id, prediction, probability
FROM cuml_random_forest_classifier(
training => (SELECT id, d0, label FROM train),
predict => (SELECT id, d0 FROM test)
)
ORDER BY row_ordinal;
Inputs
Each relation argument is a parenthesized SELECT subquery. Metadata validation resolves a registered table or view for the same role without scanning its rows. See ML Inputs for the ID, feature element, Float64 narrowing, null, finite-value, and runtime-dimension contract.
Vector element types
Feature values must be Float32 or Float64.
Arguments and options
Scalar SQL arguments
Vector binding shapes
Each relation subquery projects an id and either feature columns in dimension order or one list column, with the element types listed under Vector element types. The training relation also projects an Int32 label; the predict relation omits it. Nullable field types are accepted. A null ID, feature value, list row, list element, or label fails the query.
The list-column shape excludes other feature columns. See ML Inputs for the allowed list containers and runtime checks.
Output
The output schema depends on the call. Run gpu_validate_call against registered relations to inspect the schema that the validated ID types and literal options produce.
Examples
How many mistakes does each classifier make in a later quarter?
Logistic regression and random forest train on 1,560,000 Win32 files from weeks 0 to 51, using the same 512 normalized byte and byte-entropy histogram features. Evaluation uses 359,994 later Win32 files from weeks 52 to 63 and counts both benign files flagged and malicious files missed.
The query fits both models, predicts labels for the later files, then
joins the known labels and aggregates the errors.
Predictions are class IDs 0 and 1. Test labels are joined after prediction.
-- Unified temporal comparison training both logistic regression and random forest
-- on the full deduplicated Win32 training dataset (~1.56M files) and predicting on
-- the full held-out Win32 test dataset (359,994 files).
-- Evaluates both query-local classifiers side-by-side in one GPU statement.
WITH logistic AS (
SELECT p.id, p.prediction, m.label, m.week_id, m.sha256, m.family
FROM cuml_logistic_regression(
training => (
SELECT v.id, v.histogram AS vector, v.label
FROM ember_research_vectors_train v
JOIN ember_metadata_train m ON m.id = v.id
WHERE m.file_type = 'Win32'
ORDER BY v.id
),
predict => (
SELECT v.id, v.histogram AS vector
FROM ember_research_vectors_test v
JOIN ember_metadata_test m ON m.id = v.id
WHERE m.file_type = 'Win32'
ORDER BY v.id
),
max_iter => 1000,
penalty_l2 => 1.0
) p
JOIN ember_metadata_test m ON m.id = p.id
),
random_forest AS (
SELECT p.id, p.prediction, m.label, m.week_id, m.sha256, m.family
FROM cuml_random_forest_classifier(
training => (
SELECT v.id, v.histogram AS vector, v.label
FROM ember_research_vectors_train v
JOIN ember_metadata_train m ON m.id = v.id
WHERE m.file_type = 'Win32'
ORDER BY v.id
),
predict => (
SELECT v.id, v.histogram AS vector
FROM ember_research_vectors_test v
JOIN ember_metadata_test m ON m.id = v.id
WHERE m.file_type = 'Win32'
ORDER BY v.id
),
n_trees => 100,
max_depth => 12,
seed => 42
) p
JOIN ember_metadata_test m ON m.id = p.id
),
classified AS (
SELECT 'logistic' AS model, id, prediction, label FROM logistic
UNION ALL
SELECT 'random_forest' AS model, id, prediction, label FROM random_forest
)
SELECT model, COUNT(*) AS files,
SUM(CASE WHEN prediction = 1 AND label = 1 THEN 1 ELSE 0 END) AS true_positive,
SUM(CASE WHEN prediction = 1 AND label = 0 THEN 1 ELSE 0 END) AS false_positive,
SUM(CASE WHEN prediction = 0 AND label = 1 THEN 1 ELSE 0 END) AS false_negative,
SUM(CASE WHEN prediction = 0 AND label = 0 THEN 1 ELSE 0 END) AS true_negative
FROM classified
GROUP BY model
ORDER BY model;
The later test set contains 179,994 benign and 180,000 malicious files.
The query took 1256.11 s.
Random forest flags 15,440 fewer benign files and misses 7,118 fewer malicious files in this fit. It still misses 23,468 malicious files. These results describe one fit with the recorded options. Repeated training can change the logistic result.
The full-cohort capture records the query ID, cohort counts and observed repeat range.
Limits
- Classifier labels must be Int32 contiguous classes 0..C-1; regressor labels must be finite Float32. Null labels fail the query. Predict must omit label and match the training feature dimension.
- Prediction imports the fitted forest into nvForest and scores the predict relation on the GPU; a classifier tie resolves to the lowest class index. Training and prediction inputs are limited to i32::MAX rows and the packed feature matrix to i32::MAX elements; the random forest path does not batch rows.
- probability covers only the predicted class; per-class probabilities are not returned. Class weights are not exposed, so threshold probability to trade precision for recall.
- Training uses one RAFT pool stream whose allocations share the query grant. The forest is query-local; an empty predict relation returns an empty result.
- seed sets the bootstrap rows and feature subsets; with the same input row order, a refit on the same GPU grows the same forest.
- Float64 features, as wide columns or list elements, are narrowed to Float32 on the device before training or inference. Each value rounds to the nearest Float32, which keeps about seven significant digits; a value beyond the Float32 range becomes infinite and fails the query.