3.8.1 Row Explanations

ML_EXPLAIN_ROW explains predictions for one or more rows of unlabeled data. It is invoked using a SELECT statement. For ML_EXPLAIN_ROW parameter descriptions, see Section 3.16.7, “ML_EXPLAIN_ROW”.

Before running ML_EXPLAIN_ROW, ensure that the model you want to use is loaded; for example:

mysql> CALL sys.ML_MODEL_LOAD(@census_model, NULL);

For more information about loading models, see Section 3.14.3, “Loading Models”.

The following example generates explanations for a single row of unlabeled data, which is assigned to a @row_input session variable:

mysql> SET @row_input = JSON_OBJECT( 
          "age", 25, 
          "workclass", "Private", 
          "fnlwgt", 226802, 
          "education", "11th", 
          "education-num", 7, 
          "marital-status", "Never-married", 
          "occupation", "Machine-op-inspct", 
          "relationship", "Own-child", 
          "race", "Black", 
          "sex", "Male", 
          "capital-gain", 0, 
          "capital-loss", 0, 
          "hours-per-week", 40, 
          "native-country", "United-States");

mysql> SELECT sys.ML_EXPLAIN_ROW(@row_input, @census_model, 
          JSON_OBJECT('prediction_explainer', 'permutation_importance')));

where:

• @row_input is a session variable containing a row of unlabeled data. The data is specified in JSON key-value format. The column names must match the feature column names in the training dataset.

• @census_model is the session variable that contains the model handle.

• prediction_explainer provides the name of the prediction explainer that you have trained for this model, either the Permutation Importance prediction explainer or the SHAP prediction explainer. You train this using the ML_EXPLAIN routine (see Section 3.6, “Training Explainers”).

ML_EXPLAIN_ROW output includes a prediction, the features used to make the prediction, and a weighted numerical value that indicates feature importance, in the following format: "feature_attribution": value. The output includes a Notes field that identifies features with the greatest impact on predictions and reports a warning if the model is low quality.

You can also run ML_EXPLAIN_ROW on multiple rows of data selected from a table. For an example, refer to the syntax examples in Section 3.16.7, “ML_EXPLAIN_ROW”.