ML Inputs

cuml_tsvd, cuml_hdbscan, cuml_umap, and cuml_forest_predict accept one input relation. cuml_logistic_regression, cuml_random_forest_classifier, and cuml_random_forest_regressor require both training and predict relations. cuml_forest_predict scores its input relation against a pretrained model rather than fitting one. Its feature contract otherwise follows the wide or list shape below. Each relation argument is a parenthesized SELECT. For metadata-only gpu_validate_call, register tables or views with the corresponding schemas. Validation does not scan rows.

Identity and feature projection

Each input must project a column named id. Its Arrow type must be Int32, Int64, Utf8, LargeUtf8, or Utf8View, and no ID may be null. Duplicate IDs are allowed. The output row_ordinal distinguishes rows with the same ID and records their position in the evaluated relation.

Input order

A relation argument's top-level ORDER BY fixes the evaluated row order, so row_ordinal follows it and the model fits rows in that order. Each sort key must be an output column of the subquery, named or given by 1-based position. Any other key is rejected with input_ordering_key_not_projected, except under LIMIT, OFFSET, or FETCH, where the ORDER BY only selects rows. Without a top-level ORDER BY, input order is unspecified and can change between runs. Rows that tie on every key have no stable order, so a reproducible fit with a fixed random_state needs a key that is unique per row, such as ORDER BY id over distinct IDs.

The relation projects exactly one of these dense-feature shapes:

• Wide features: every column other than id is a Float32 or Float64 feature. For training, the canonical label column is excluded from features. The order of columns in the SELECT projection fixes the dimension order. At least one feature is required.
• List features: the only column besides id (and the training label) is a FixedSizeList<T, D>, List<T>, or LargeList<T> whose element T is Float32 or Float64, under any name. A list column next to other feature columns is rejected with list_vector_with_additional_features. FixedSizeList requires positive D; variable-length lists must have the same positive length for every evaluated row.

Null values

Schema nullability does not matter. A nullable field type is accepted for the ID, for every feature column, for a list column and its elements, and for the training label. Results of aggregates, Parquet columns, and lists built in SQL therefore need no rewrite. The contract applies to values. A null ID, feature value, list row, list element, or label fails the query with an invalid-input error (rapids_invalid_input) that names the function, the relation role, and the column.

Add COALESCE(column, CAST(0 AS REAL)) only when the data contains nulls and a fallback value is correct, or drop the offending rows with WHERE column IS NOT NULL.

A list vector built in SQL with ARRAY_AGG, MAKE_ARRAY, or COALESCE(..., ARRAY_REPEAT(...)) is computed by DataFusion on the CPU, because native lowering does not build lists. Its result is uploaded as the relation and accepted when it contains no null rows or elements.

cuML trains and predicts on Float32. Every function except cuml_forest_predict narrows Float64 features, wide columns and list elements alike, to Float32 on the device before the native call, so SQL literals, make_array over DOUBLE values, and DOUBLE Parquet columns need no cast. Each value rounds to the nearest Float32, which keeps about seven significant digits, and a value beyond the Float32 range becomes infinite and fails the finite-value check. cuml_forest_predict takes Float32 features only, because the model's own precision decides the width on the device. Narrowing packs the Float64 values first and then writes the Float32 copy, so the pack stage briefly holds both under the query's memory cap. A CAST to REAL in the subquery avoids that when a query runs close to its cap. Apply CAST in the subquery for any other numeric type:

SELECT id, pc_0
FROM cuml_tsvd(
  input => (SELECT id, CAST(d0 AS FLOAT) AS d0, CAST(d1 AS FLOAT) AS d1 FROM input_vectors),
  n_components => 1
);

Float32 feature values must be finite. The unsupervised input role treats a column named label as an ordinary feature.

Supervised classification and regression

For classification, training projects a canonical Int32 column named label alongside its ID and features. Evaluated training labels must contain at least two classes with contiguous indices 0..C-1. Two classes use logistic loss; more classes use softmax for logistic regression. A fit that reaches max_iter remains a result. Random forest classification accepts the same class indices. For random forest regression, training.label must be finite Float32. Its output prediction is Float32. The model is released after the call returns its predictions.

predict projects its own id and features, without label. Its feature dimension must match training. Known dimensions are checked at planning, and evaluated dimensions are checked after packing. Output id comes from predict, including when the training and predict ID types differ. An empty evaluated predict relation produces zero rows with the stable prediction Int32 and probability Float32 schema for classification or prediction Float32 for regression without calling the native model.

Classifier probabilities

cuml_logistic_regression and cuml_random_forest_classifier return prediction, the most probable class (a tie takes the lowest index), and probability Float32, the probability of that class. The number of classes is learned from the labels, so the output has no per-class columns.

• Logistic regression follows cuML's predict_proba. Two classes apply the sigmoid to the decision score of class 1, which makes probability at least 0.5. Three or more classes apply softmax to the per-class decision scores, which makes it at least 1 / C.
• The random forest averages each tree's leaf probabilities for the class and reports the largest average.

For two classes, rank rows by the probability of class 1:

SELECT id,
       CASE WHEN prediction = 1 THEN probability ELSE 1 - probability END AS score
FROM cuml_logistic_regression(training => (...), predict => (...))
ORDER BY score DESC;

Class weights are not exposed. To trade precision for recall, threshold this score instead of prediction, which cuts at 0.5.

Relation size

cuDF indexes the values of a list column with 32-bit offsets. One relation argument, or one intermediate result inside its subquery, can hold at most 2,147,483,647 list values per column: 1,048,575 rows of a 2048-wide FixedSizeList feature. Scans and filters over larger Parquet files run. The source planner reads each file in parts under the limit, sized from the footer's value counts or, without a footer, from fixed list widths. A larger relation fails with size_overflow, naming the column, the value count and the row count that fits. Filter or sample the training relation below that row count, since one call trains one model. A predict or input relation can be split into row ranges, one call each, and combined with UNION ALL.

Validation boundary

SQL planning and gpu_validate_call check names, static Arrow types, list shape, option ranges, and known dimensions. A known dimension smaller than n_components is rejected before execution. Metadata validation reads no values, so it cannot find nulls.

Execution checks evaluated row count and values: no nulls in IDs, features, or labels, finite features, and uniform positive list length. An empty evaluated input produces zero rows with the UDTF's stable output schema without calling cuML. For a nonempty input, TSVD requires at least two rows and two feature dimensions, and n_components cannot exceed the evaluated dimension. HDBSCAN requires at least two rows, min_samples < rows, min_cluster_size <= rows, and max_cluster_size <= rows when the latter is nonzero. UMAP requires at least two rows and n_neighbors < rows. When an exact row count is known, SQL planning can reject invalid counts. Otherwise the execution error carries a specific reason for the violated row-dependent condition.