The ML.WEIGHTS function

This document describes theML.WEIGHTS function, which lets you see theunderlying weights that a model uses during prediction. This function applies tolinear and logistic regression modelsandmatrix factorization models.

For matrix factorization models, you can use theAI.GENERATE_EMBEDDING functionas an alternative to theML.WEIGHTS function.AI.GENERATE_EMBEDDING generates the same factor weights and intercept data asML.WEIGHTS as an array in a single column, rather than in two columns.Having all of the embeddings in a single column lets you directly use theVECTOR_SEARCH functionon theAI.GENERATE_EMBEDDING output.

Syntax

ML.WEIGHTS(  MODEL `PROJECT_ID.DATASET.MODEL`,  STRUCT([,STANDARDIZE AS standardize]))

Arguments

ML.WEIGHTS takes the following arguments:

• PROJECT_ID: your project ID.
• DATASET: the BigQuery dataset that containsthe model.
• MODEL: the name of the model.
• STANDARDIZE: aBOOL value that specifies whether themodel weights should be standardized to assume that all features have a meanof0 and a standard deviation of1. Standardizing the weights allows theabsolute magnitude of the weights to be compared to each other. The defaultvalue isFALSE. This argument only applies to linear and logistic regressionmodels.

Output

ML.WEIGHTS has different output columns for different model types.

Linear and logistic regression models

For linear and logistic regression models,ML.WEIGHTS returns thefollowing columns:

• trial_id: anINT64 value that contains the hyperparameter tuning trial ID.This column is only returned if you ran hyperparameter tuning when creatingthe model.
• processed_input: aSTRING value that contains the name of the featureinput column. The value of this column matches the name of thefeature column provided in thequery_statement clausethat was used when the model was trained.
• weight: if the column identified by theprocessed_input value isnumerical,weight contains aFLOAT64 value and thecategory_weightscolumn containsNULL values. If the column identified by theprocessed_input value is non-numerical and has been converted to one-hotencoding, theweight column isNULL and thecategory_weightscolumn contains the category names and weights for each category.
• category_weights.category: aSTRING value that contains the categoryname if the column identified by theprocessed_input value is non-numeric.
• category_weights.weight: aFLOAT64 that contains the category's weightif the column identified by theprocessed_input value is non-numeric.
• class_label: aSTRING value that contains the label for agiven weight. Only used for multiclass models. The output includes one rowper<class_label, processed_input> combination.

If you used theTRANSFORM clausein theCREATE MODEL statement that created the model,ML.WEIGHTS outputsthe weights ofTRANSFORM output features. The weights are denormalized bydefault, with the option to get normalized weights, exactly like models thatare created withoutTRANSFORM.

Matrix factorization models

For matrix factorization models,ML.WEIGHTS returns the following columns:

• trial_id: anINT64 value that contains the hyperparameter tuning trial ID.This column is only returned if you ran hyperparameter tuning when creatingthe model.
• processed_input: aSTRING value that contains the name of the user oritem column. The value of this column matches the name of theuser or item column provided in thequery_statement clausethat was used when the model was trained.
• feature: aSTRING value that contains the names of the specific users oritems used during training.
• factor_weights: anARRAY<STRUCT> value that contains the factors and theweights for each factor.
  • factor_weights.factor: anINT64 value that contains the latent factorfrom training. This value can be between1 and the value of theNUM_FACTORS option.
  • factor_weights.weight: aFLOAT64 value that contains theweightof the respective factor and feature.
• intercept: aFLOAT64 value that contains the intercept or bias term fora feature.

There is an additional row in the output that contains theglobal__intercept__ value calculated from the input data. This row hasNULLvalues for theprocessed_input andfactor_weights columns. Forimplicit feedbackmodels,global__intercept__ is always 0.

Examples

The following examples show how to useML.WEIGHTS with and without thestandardize argument.

Without standardization

The following example retrieves weight information frommymodel inmydataset. The dataset is in your default project. It returns the weightsthat are associated with each one-hot encoded category for the input columninput_col.

SELECTcategory,weightFROMUNNEST((SELECTcategory_weightsFROMML.WEIGHTS(MODEL`mydataset.mymodel`)WHEREprocessed_input='input_col'))

This command uses theUNNESTfunction because thecategory_weights column is a nested repeated column.

With standardization

The following example retrieves weight information frommymodel inmydataset. The dataset is in your default project. It retrieves standardizedweights, which assume all features have a mean of0 and a standard deviationof1.

SELECT*FROMML.WEIGHTS(MODEL`mydataset.mymodel`,STRUCT(trueASstandardize))

What's next

• For more information about model weights support in BigQuery ML, seeBigQuery ML model weights overview.
• For more information about supported SQL statements and functions for MLmodels, seeEnd-to-end user journeys for ML models.