Random Forest Regressor

UDTF: cuml_random_forest_regressor

Official cuML reference: Python API

Fit a query-local cuML random forest regressor 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
FROM cuml_random_forest_regressor(
  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, Float32 feature, null, finite-value, and runtime-dimension contract.

Role	Required	Validation reference	Description
training	yes	table	Dense Float32 features and non-null Int32 label used to fit the query-local model.
predict	yes	table	Independent dense Float32 rows scored with the query-local model; must omit label.

Vector element types

Element type	Valid metrics
Float32	Not applicable

Arguments and options

Scalar SQL arguments

Argument	Type	Required	Description
n_trees	integer	no	Number of trees.
max_depth	integer	no	Maximum tree depth; zero uses the native unlimited depth.
max_leaves	integer	no	Maximum leaf count; omission uses the native unlimited setting.
max_features	number	no	Fraction of features sampled per split.
max_samples	number	no	Fraction of training rows sampled per tree.
bootstrap	boolean	no	Sample training rows with replacement.
max_n_bins	integer	no	Maximum histogram bins.
min_samples_leaf	integer	no	Minimum samples per leaf.
min_samples_split	integer	no	Minimum samples to split a node.
min_impurity_decrease	number	no	Minimum split impurity reduction.
max_batch_size	integer	no	Maximum prediction batch size.
seed	integer	no	Training random seed.

SQL value argument schemas

Argument	Required	Literal shape	Default	Constraints	Description
bootstrap	no	boolean	true		Sample training rows with replacement.
max_batch_size	no	integer	4096	minimum 1; maximum 2147483647	Maximum prediction batch size.
max_depth	no	integer	16	minimum 0; maximum 2147483647	Maximum tree depth; zero uses the native unlimited depth.
max_features	no	number	1	greater than 0; maximum 1	Fraction of features sampled per split.
max_leaves	no	integer	No default	minimum 1; maximum 2147483647	Maximum leaf count; omission uses the native unlimited setting.
max_n_bins	no	integer	128	minimum 2; maximum 2147483647	Maximum histogram bins.
max_samples	no	number	1	greater than 0; maximum 1	Fraction of training rows sampled per tree.
min_impurity_decrease	no	number	0	minimum 0	Minimum split impurity reduction.
min_samples_leaf	no	integer	1	minimum 1; maximum 2147483647	Minimum samples per leaf.
min_samples_split	no	integer	2	minimum 2; maximum 2147483647	Minimum samples to split a node.
n_trees	no	integer	100	minimum 1; maximum 2147483647	Number of trees.
seed	no	integer	0	minimum 0; maximum 18446744073709551615	Training random seed.

Vector binding shapes

Each relation subquery projects a non-null id and either non-null Float32 feature columns in dimension order or one non-null vector list column of non-null Float32 values. For classification, training also projects non-null Int32 label; regression requires non-null finite Float32 label. The predict relation omits it.

The list-column shape excludes other feature columns. See ML Inputs for the allowed list containers and runtime checks.

Output

Column	Type	Nullable	Description
row_ordinal	UInt64	no	Evaluated input row position, including when IDs repeat. Follows the input's top-level ORDER BY on output columns; unspecified without one.
id	same_as_predict.id	no	Logical ID from the predict relation.
prediction	Float32	no	Predicted regression target.

Concrete schemas are call-specific. Run gpu_validate_call against registered relations to inspect the output schema after the actual ID types and literal options are validated.

Limits

• Validation resolves named tables or views and reads schemas only; it does not execute relation scans or GPU work.
• Execution relation arguments require parenthesized subqueries; dry-run validation accepts registered named relations only.
• Classifier labels must be non-null Int32 contiguous classes 0..C-1; regressor labels must be non-null finite Float32. 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.
• 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.

To dry-run validate relation metadata, column types, and options without execution, see gpu_validate_call.