3.10.7 ML_EXPLAIN_TABLE

ML_EXPLAIN_TABLE explains predictions for an entire table of unlabeled data and saves results to an output table.

ML_EXPLAIN_TABLE is a compute intensive process. Limiting operations to batches of 10 to 100 rows by splitting large tables into smaller tables is recommended.

ML_EXPLAIN_TABLE limits explanations to the 100 most relevant features.

A loaded model is required to run ML_EXPLAIN_TABLE. See Section 3.9.3, “Loading Models”.

ML_EXPLAIN_TABLE Syntax

CALL sys.ML_EXPLAIN_TABLE(table_name, model_handle, output_table_name, options);

ML_EXPLAIN_TABLE parameters:

• table_name: Specifies the fully qualified name of the input table (schema_name.table_name). The input table should contain the same feature columns as the table used to train the model but no target column.

• model_handle: Specifies the model handle or a session variable containing the model handle.

• output_table_name: Specifies the table where explanation data is stored. The table is created if it does not exist. A fully qualified table name must be specified (schema_name.table_name). If the table already exists, an error is returned.

• options: Optional parameters specified as key-value pairs in JSON_OBJECT() format. If an option is not specified, the default setting is used. The available options are:

  • prediction_explainer: The name of the prediction explainer that you have trained for this model using ML_EXPLAIN. Valid values are:

    • permutation_importance: The default prediction explainer.

    • shap: The SHAP prediction explainer, which produces global feature importance values based on Shapley values.

Syntax Examples

• The following example generates explanations for a table of data with the default Permutation Importance prediction explainer. The ML_EXPLAIN_TABLE call specifies the fully qualified name of the table to generate explanations for, the session variable containing the model handle, and the fully qualified output table name. The SELECT statement retrieves explanation data from the output table.

  CALL sys.ML_EXPLAIN_TABLE('ml_data.iris_test', @iris_model, 
  'ml_data.iris_explanations', NULL);
  
  SELECT * FROM ml_data.iris_explanations;

• Run ML_EXPLAIN_TABLE with the Permutation Importance prediction explainer:

  CALL sys.ML_EXPLAIN_TABLE('ml_data.`iris_test_temp`', @model, 
  'ml_data.`iris_explanations`', JSON_OBJECT(
  'prediction_explainer', 'permutation_importance'));