ML tools reference

The machine learning (ML) tools work with data stored in the Vertica database and cover the full workflow from preparing data, exploring it, training models, generating predictions, and evaluating results to managing model versions through a governed registry.

Every tool operates on tables identified as table or schema.table. If no schema is specified, the default public schema is used. Most tools also accept optional sandbox and subcluster parameters to route the request to a specific node group.

Execution modes

Each tool runs in one of two modes:

• Synchronous: The result is returned immediately in the tool response.
• Asynchronous: A job_id is returned immediately. Use get_job_status(job_id) to poll for completion, and then get_job_results(job_id) to retrieve the output.

Tool categories

• Data preparation: Tools for splitting, cleaning, encoding, normalizing, and transforming data before model training.
• Exploratory data analysis: Tools for understanding data characteristics, relationships, and quality issues prior to modeling.
• Model training: Tools for training supervised, unsupervised, and time-series models directly inside the database.
• Prediction: Tools for scoring new data using a trained or registered model.
• Model evaluation: Tools for measuring model quality and understanding what drives predictions.
• Model registry and governance: Tools for registering trained models under a versioned family name and managing their lifecycle status.

Data preparation

Tools for splitting, cleaning, encoding, normalizing, and transforming data before model training.

ml_train_test_split

Splits a source table into training and testing tables using a seeded random partition. Both splits run concurrently as independent background jobs.

Asynchronous. Returns job_id values immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table name (schema.table or table).
test_ratio	number	no	Fraction of rows allocated to the test set, 0.0–1.0 (default: 0.3).
seed	number	no	Random seed for a reproducible split (default: 42).
output_prefix	string	no	Prefix for the output tables ({prefix}_train and {prefix}_test). Auto-generated if omitted.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
train_job_id	Asynchronous job identifier for the training table creation; use get_job_status(job_id) to monitor.
test_job_id	Asynchronous job identifier for the testing table creation; use get_job_status(job_id) to monitor.
train_table	Fully qualified name of the training table (available once train_job_id completes).
test_table	Fully qualified name of the testing table (available once test_job_id completes).
status	Job status at submission time (pending).

ml_impute

Imputes (fills) missing NULL values in a table using mean, mode, forward-fill, backward-fill, or an automatic method.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table name (schema.table or table).
method	string	no	Imputation method: mean, mode, ffill, bfill, or auto (default: auto). The auto method selects mean for numeric columns and mode for categorical columns.
columns	array	no	Columns to impute. Required for ffill/bfill. Omit for mean/mode to impute all suitable columns.
partition_columns	array	no	Optional columns to group or partition imputation by.
order_by	string	no	Column to order by; required for ffill and bfill.
output_view	string	no	Name for the output view. Auto-generated if omitted.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
job_id	Asynchronous job identifier; use get_job_status(job_id) to monitor progress.
output_view	Fully qualified name of the view that will contain imputed data once the job completes.
status	Job status at submission time (pending).
message	Human-readable summary including the job_id and output_view name.

ml_encode_columns

Encodes categorical columns into numeric representations using one-hot or label encoding, persisting the encoder artifacts for reuse on new data.

Synchronous. Returns the result immediately.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table name (schema.table or table).
columns	array	yes	Column names to encode.
encoding_type	string	yes	Encoding method: one_hot or label.
output_table	string	no	Output table name. A persistent staging table is auto-created if omitted.
overwrite	boolean	no	If true, overwrite an existing encoder model for a permanent output_table (default: false).
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
output_table	Fully qualified name of the created table.
columns_encoded	List of columns that were encoded.
row_count	Number of rows in the output table.
encoder_model_name	One-hot only: the model holding the category vocabulary, for reapplication to new data with ml_apply_encoding.
label_mapping_tables	Label only: object mapping {column: mapping_table}, for reapplication to new data with ml_apply_encoding.

ml_apply_encoding

Applies a previously fit encoder or label mapping to a new source table (for example, test or inference data), producing the same schema as the training-side encoding.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table to encode (schema.table or table).
columns	array	yes	Columns to encode; should match the columns fit on the training side.
encoding_type	string	yes	Encoding method: one_hot or label (must match the method used at fit time).
encoder_model_name	string	no	Required for one_hot. Fully qualified encoder model name returned by ml_encode_columns.
label_mapping_tables	object	no	Required for label. Object mapping {column: mapping_table} returned by ml_encode_columns.
output_table	string	no	Output table name. A persistent staging table is auto-created if omitted.
overwrite	boolean	no	If true and output_table already exists, drop it before writing (default: false).
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
job_id	Asynchronous job identifier; use get_job_status(job_id) to monitor progress.
output_table	Fully qualified name of the encoded table (available once the job completes).
columns_encoded	List of columns that were encoded.
status	Job status at submission time (pending).
message	Human-readable summary including the job_id and output_table name.

ml_normalize_fit

Computes and persists normalization parameters (min-max, z-score, or robust scaling) as a reusable model, optionally materializing a normalized view.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table name (schema.table or table).
columns	array	yes	Numeric column names to normalize.
normalization_method	string	yes	Normalization technique: minmax, zscore, or robust_zscore.
model_name	string	yes	Name for the normalization model to persist.
output_view	string	no	Optional name for a view with the normalized data. No view is created if omitted.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
job_id	Asynchronous job identifier; use get_job_status(job_id) to monitor progress.
model_name	Name under which the normalization model will be saved.
output_view	Fully qualified name of the view that will be created, if output_view was provided.
status	Job status at submission time (pending).
message	Human-readable summary including the job_id and model_name.

ml_apply_normalize

Applies a previously persisted normalization model to a source table, using the same scaling that was computed at fit time.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table to normalize (schema.table or table).
model_name	string	yes	Name of the persisted normalization model.
output_table	string	yes	Name for the output table with normalized data.
columns	array	no	Columns to validate against the source table before submitting the job. The normalization scope is always determined by the fitted model.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
job_id	Asynchronous job identifier; use get_job_status(job_id) to monitor progress.
output_table	Fully qualified name of the table that will be created when the job completes.
status	Job status at submission time (pending).
message	Human-readable summary including the job_id and output_table name.

ml_normalize

Normalizes numeric columns using min-max, z-score, or robust scaling and exposes the result as a view, without persisting a reusable model.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table name (schema.table or table).
columns	array	yes	Numeric column names to normalize.
normalization_method	string	yes	Normalization technique: minmax, zscore, or robust_zscore.
output_view	string	yes	Name of the view showing the input relation with normalized data.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
job_id	Asynchronous job identifier; use get_job_status(job_id) to monitor progress.
output_view	Fully qualified name of the view that will be created when the job completes.
status	Job status at submission time (pending).
message	Human-readable summary including the job_id and output_view name.

ml_svd

Performs Singular Value Decomposition (SVD) on a numeric data matrix and persists the result as a reusable model.

Synchronous. Returns the result immediately.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table name (schema.table or table).
model_name	string	yes	Name for the SVD model to fit and save.
columns	array	no	Numeric column names to include. If omitted, all columns in the source table are used.
exclude_columns	array	no	Column names to exclude from processing.
num_components	number	no	Number of singular values/vectors to compute. If omitted, all components are kept.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
model_name	Name of the persisted SVD model.
message	Human-readable summary of the SVD performed and model persistence.

ml_apply_svd

Applies a previously computed SVD model to a new data matrix, using the same feature extraction that was computed at fit time.

Synchronous. Returns the result immediately.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table to transform (schema.table or table).
model_name	string	yes	Name of the persisted SVD model.
output_table	string	yes	Name for the output table with transformed data.
columns	array	no	Columns containing the data matrix. If omitted, all columns are used.
exclude_columns	array	no	Column names to exclude from processing.
key_columns	array	no	Columns identifying source rows (for example, IDs) to carry through into the output table.
num_components	number	no	Desired output dimensionality. If omitted, matches the number of components retained at fit time.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
output_table	Fully qualified name of the transformed table.
message	Human-readable summary of the transformation performed and the output table created.

ml_pca

Fits a PCA (Principal Component Analysis) model on a table and saves it in the Vertica model catalog for subsequent use with ml_apply_pca.

Synchronous. Returns the result immediately.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table or view (schema.table or table). All columns must be numeric.
columns	array	yes	Numeric column names to include in the PCA fit.
model_name	string	yes	Name for the PCA model to create (schema.name or just name). Must not already exist.
num_components	number	no	Number of principal components to retain. If omitted, all components are kept.
scale	boolean	no	If true, standardize columns using a correlation matrix instead of covariance. Recommended when columns have very different scales.
method	string	no	Computation method. The only supported value is LAPACK. Omit to use the default.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
model_name	Fully qualified name of the created PCA model, for use with ml_apply_pca.
message	Human-readable summary including accepted and rejected row counts.

ml_apply_pca

Transforms data using a fitted PCA model and writes the principal component coordinates to an output table.

Synchronous. Returns the result immediately.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table to transform (schema.table or table).
model_name	string	yes	Name of the fitted PCA model (returned by ml_pca).
columns	array	yes	Numeric column names to transform with the PCA model.
output_table	string	no	Name for the output table with transformed (PCA) data.
num_components	number	no	Number of principal components to retain in the output. Defaults to the number fit in the model.
cutoff	number	no	The minimum cumulative explained variance to retain. Determines the number of components to keep.
match_by_pos	boolean	no	If true, match input columns to model columns by position instead of by name.
key_columns	array	no	Columns identifying source rows to carry through into the output table.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
output_table	Fully qualified name of the transformed table.
message	Human-readable summary of the transformation performed and the output table created.

Exploratory data analysis

Tools for understanding data characteristics, relationships, and quality issues prior to modeling.

ml_correlation_matrix

Computes the pairwise correlation matrix for numeric columns in a table, useful for exploratory analysis and feature selection.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table name (schema.table or table).
columns	array	no	Columns to include. If omitted, all numeric and boolean columns are used.
method	string	no	Correlation method: pearson (default), spearman, or spearmand.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
columns	Ordered list of column names forming the matrix axes.
matrix	N x N matrix where matrix[i][j] is the correlation between columns[i] and columns[j]; the diagonal is always 1.0.
method	The correlation method that was used.
message	Summary including matrix dimensions, with a cost warning when more than 50 columns are used.

ml_detect_outliers

Detects outliers in one or more numeric columns using statistical thresholds (z-score, robust z-score, or IQR).

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
table	string	yes	Source table name (schema.table or table).
columns	array	yes	One or more numeric columns to analyze; a row is flagged if any column exceeds the threshold.
method	string	no	Detection method: z_score (default), robust_zscore, or iqr.
threshold	number	no	Sensitivity cutoff (default: 3.0 for z_score/robust_zscore, 1.5 for iqr).
limit	number	no	Maximum number of outlier rows returned; the total count is always exact (default: 100).
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
columns	Active columns used for detection.
method	The detection method used.
threshold	The effective threshold value.
outlier_count	Total number of outlier rows in the table (not capped by limit).
outlier_rows	Up to limit flagged rows, each with its column values and which columns triggered the flag.
skipped_columns	Columns excluded because their statistic was zero or NULL.
message	Human-readable summary including table, columns, method, threshold, and count.

Model training

Tools for training supervised, unsupervised, and time-series models directly inside the database.

ml_train_model

Trains Vertica in-database machine learning model, covering classification, regression, clustering, decomposition, and anomaly-detection algorithms.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
algorithm	string	yes	Algorithm: bisecting_kmeans, iforest, kmeans, kprototypes, linear_reg, logistic_reg, naive_bayes, pca, pls_reg, poisson_reg, rf_classifier, rf_regressor, svd, svm_classifier, svm_regressor, xgb_classifier, or xgb_regressor.
input_table	string	yes	Training data table name. Unqualified temp table names are auto-materialized into a persistent staging table before training.
predictor_columns	array	yes	Predictor/feature column names.
target_column	string	no	Target/response column; required for supervised algorithms, omitted for clustering/decomposition.
model_name	string	no	Custom model name (auto-generated as mcp_ml_{algorithm}_{YYYYMMDD_HHMMSS} if omitted).
num_clusters	number	no	Number of clusters; required for kmeans, bisecting_kmeans, and kprototypes.
params	object	no	Algorithm-specific parameter overrides as key-value pairs (for example, {"max_iterations": "200"}).
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
job_id	Asynchronous job identifier; use get_job_status(job_id) to track training progress.
model_name	The model name, for use with prediction and evaluation tools once training completes.
algorithm	The algorithm used.
status	Job status at submission time (pending).

ml_train_timeseries

Trains a time-series model (ARIMA, autoregressor, or moving average) on a table of observed values.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
algorithm	string	yes	Time-series algorithm: arima, autoregressor, or moving_average.
input_table	string	yes	Training data table (schema.table).
timeseries_columns	array	yes	Column(s) with the observed time-series values. One column for univariate; two or more for a multivariate autoregressor (VAR).
timestamp_column	string	yes	Column containing timestamps or sequence indices; must be sortable.
model_name	string	no	Custom model name (auto-generated if omitted).
params	object	no	Algorithm-specific parameter overrides (for example, {"p": "2", "d": "1", "q": "1"} for ARIMA).
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
job_id	Asynchronous job identifier; use get_job_status(job_id) to track training progress.
model_name	Fully qualified model name, for use with prediction tools once training completes.
status	Job status at submission time (pending).

ml_cross_validate

Evaluates an ML algorithm using k-fold cross-validation, optionally with hyperparameter grid search, for a statistically robust performance estimate without a separate test set.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
algorithm	string	yes	Algorithm: logistic_reg, linear_reg, naive_bayes, svm_classifier, or svm_regressor.
input_table	string	yes	Training data table (schema.table or table).
predictor_columns	array	yes	Feature column names.
target_column	string	yes	Target/response column name.
model_name	string	no	Custom model name; auto-generated if omitted. The model is always persisted so results can be retrieved after completion.
metrics	string	no	Metrics to compute as a comma-separated string or JSON array (default: accuracy).
fold_count	number	no	Number of folds for k-fold cross-validation (default: 5, minimum: 2).
hyperparams	string	no	JSON hyperparameter grid to search, for example {"C":[1,5,10]}. One result row per combination.
prediction_cutoff	number	no	Classification threshold for logistic_reg only (exclusive range 0–1, default: 0.5).
params	object	no	Algorithm-specific parameter overrides as key-value pairs.
schema	string	no	Default schema for the source table (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
job_id	Asynchronous job identifier; use get_job_status(job_id) to track progress.
model_name	Fully qualified name of the saved cross-validation model.
algorithm	Algorithm used.
fold_count	Number of folds used.
status	Job status at submission time (pending).
message	Human-readable summary with next-step instructions.

To get the averaged metric results, run get_model_attribute on the saved model.

Prediction

Tools for scoring new data using a trained or registered model.

ml_predict

Runs predictions using a trained Vertica ML model, producing a new table with scored results.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
model_name	string	yes	Trained model name.
input_table	string	yes	Table to run predictions on.
predictor_columns	array	no	Feature column names; defaults to the model's stored training predictors.
output_table	string	no	Output table name (default: {input_table}_predictions).
params	object	no	Prediction parameter overrides (for example, {"type": "probability"}).
timestamp_column	string	no	For time-series models: the timestamp/sequence column; defaults to the training timestamp column.
num_predictions	number	no	For time-series models: number of future steps to forecast (default: 10).
use_classes	boolean	no	For supported classifiers, emit class probability columns instead of a single predicted label.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
output_table	Fully qualified name of the predictions table.
row_count	Number of rows in the output.
model_name	The model used.
algorithm	The algorithm type.
query	The SQL statement that was executed.

ml_predict_with_registered_model

Runs predictions using a registered model family name rather than a raw model name, resolving to the production version unless a specific version is requested.

Synchronous. Returns the result immediately.

Input schema:

Field	Type	Required	Description
registered_name	string	yes	Registered model family name.
input_table	string	yes	Table to run predictions on.
registered_version	number	no	Specific registered version to use; defaults to the production version.
predictor_columns	array	no	Feature column names; defaults to the model's stored training predictors.
output_table	string	no	Output table name (default: {input_table}_predictions).
params	object	no	Prediction parameter overrides beyond model_name.
timestamp_column	string	no	For time-series models: the timestamp/sequence column; defaults to the training timestamp column.
num_predictions	number	no	For time-series models: number of future steps to forecast (default: 10).
use_classes	boolean	no	For supported classifiers, emit class probability columns instead of a single predicted label.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
output_table	Fully qualified name of the predictions table.
row_count	Number of rows in the output.
registered_name	The registered model family used.
registered_version	The registered version used.
algorithm	The algorithm type.
query	The SQL statement that was executed.

Model evaluation

Tools for measuring model quality and understanding what drives predictions.

ml_classification_report

Computes classification evaluation metrics: accuracy, precision, recall, F1 score, and optionally AUC.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
table	string	yes	Table with actual and predicted values.
actual_column	string	yes	Column with actual/true labels.
predicted_column	string	yes	Column with predicted labels.
additional_metrics	array	no	Optional list of additional classification metrics to compute (for example, balanced_accuracy, mcc, fpr, npv, specificity).
include_auc	boolean	no	Whether to include ROC AUC in the output (binary classification only, default: false).
include_prc_auc	boolean	no	Whether to include PRC AUC in the output (binary classification only, default: false).
pos_label	string	no	The label of the positive class.
probability_column	string	no	Column with predicted probabilities (required for ROC/PRC AUC computation).
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
job_id	Asynchronous job identifier; use get_job_results(job_id) to retrieve the computed report once the status is completed.
status	Job status at submission time (pending).
message	Human-readable submission confirmation.

Retrieved with get_job_results:

Field	Description
accuracy, precision, recall, f1_score	Core metrics in range [0, 1]. For multiclass, precision/recall/F1 are macro-averaged.
auc	Area Under the ROC Curve (only if include_auc is true; binary classification only).
prc_auc	Area Under the Precision-Recall Curve (only if include_prc_auc is true; binary classification only).
confusion_matrix	Array of {actual_class, predicted_class, count} entries.
additional_metrics	Map of any additional_metrics that were requested.

ml_regression_report

Computes regression evaluation metrics such as MAE, MSE, RMSE, R-squared, adjusted R-squared, AIC, and BIC.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
table	string	yes	Table with actual and predicted numeric values.
actual_column	string	yes	Column with the true/actual values.
predicted_column	string	yes	Column with the predicted numeric values.
metrics	array	no	List of metrics to compute (for example, mae, mse, rmse, r2, r2_adj, aic, bic, max_error). A default report is returned if omitted.
num_predictors	number	no	Number of predictors used by the model; needed for adjusted R2, AIC, and BIC (default: 1).
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
job_id	Asynchronous job identifier; use get_job_results(job_id) to retrieve the computed report once the status is completed.
status	Job status at submission time (pending).
message	Human-readable submission confirmation.

Retrieved with get_job_results:

Field	Description
metrics	Array of {metric, value} entries, one per requested metric.

ml_features_importance

Computes normalized feature importance scores from a trained model, for model interpretation and variable selection.

Asynchronous. Returns job_id immediately. Retrieve results with get_job_results(job_id) once the status is completed.

Input schema:

Field	Type	Required	Description
model_name	string	yes	Trained model name.
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
job_id	Asynchronous job identifier; use get_job_results(job_id) to retrieve scores once the status is completed.
status	Job status at submission time (pending).
message	Human-readable submission confirmation.

Retrieved with get_job_results:

Field	Description
model_name	The model analyzed.
features	Array of {feature, importance, sign} objects; importance is normalized to 0–100 and sign indicates the direction of the relationship (+1 or -1).

Model registry and governance

Tools for registering trained models under a versioned family name and managing their lifecycle status.

ml_register_model

Registers an existing native Vertica model under a versioned, governed model family name.

Synchronous. Returns the result immediately.

Input schema:

Field	Type	Required	Description
model_name	string	yes	Existing native model name (schema.model or table).
registered_name	string	yes	Registered model family name.
schema	string	no	Schema name (default: public).
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
model_name	Fully qualified native model name that was registered.
registered_name	Registered family name.
message	Human-readable confirmation.

ml_list_registered_models

Lists registered Vertica models, including their versions, statuses, and backing native model names.

Synchronous. Returns the result immediately.

Input schema:

Field	Type	Required	Description
registered_name	string	no	Optional registered model family name to filter by.
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
models	Registered model rows with native status and version information.
count	Number of rows returned.

ml_get_production_model

Resolves the current production version of a registered model family, used when no explicit version is supplied at prediction time.

Synchronous. Returns the result immediately.

Input schema:

Field	Type	Required	Description
registered_name	string	yes	Registered model family name.
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
model	The current production row for the registered model family.

ml_change_model_status

Changes the lifecycle status of a registered model version (for example, promote to production, move to staging, archive, or decline).

Synchronous. Returns the result immediately.

Input schema:

Field	Type	Required	Description
registered_name	string	yes	Registered model family name.
registered_version	number	yes	Registered version number.
new_status	string	yes	New status: under_review, staging, production, archived, declined, or unregistered.
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
registered_name	The registered model family name.
registered_version	The version updated.
new_status	The status it was changed to.
message	Human-readable confirmation.

ml_get_model_status_history

Fetches the status-change history for a registered model, showing how it moved through lifecycle states over time.

Synchronous. Returns the result immediately.

Input schema:

Field	Type	Required	Description
registered_name	string	yes	Registered model family name.
registered_version	number	no	Optional filter to a single registered version.
sandbox	string	no	Optional sandbox name to route this request to an UP node in that sandbox. Ignored if subcluster is also specified.
subcluster	string	no	Optional subcluster name to route this request to an UP node in that subcluster.

Output:

Field	Description
history	Status history rows ordered by status_change_time.
count	Number of history rows returned.