Stay organized with collectionsSave and categorize content based on your preferences.
The ML.FEATURE_IMPORTANCE function
This document describes theML.FEATURE_IMPORTANCEfunction, which lets you
see the feature importance score. This score indicates how useful or valuable
each feature was in the construction of a boosted tree or a random forest model
during training. For more information, see thefeature_importancespropertyin the XGBoost library.
Syntax
ML.FEATURE_IMPORTANCE(
MODEL `PROJECT_ID.DATASET.MODEL`
)
Arguments
ML.FEATURE_IMPORTANCEtakes the following arguments:
PROJECT_ID: your project ID.
DATASET: the BigQuery dataset that contains
the model.
MODEL: the name of the model.
Output
ML.FEATURE_IMPORTANCEreturns the following columns:
feature: aSTRINGvalue that contains the name of the feature column
in the input training data.
importance_weight: aFLOAT64value that contains the number of times a
feature is used to split the data across all trees.
importance_gain: aFLOAT64value that contains the average gain across all
splits the feature is used in.
importance_cover: aFLOAT64value that contains the average coverage
across all splits the feature is used in.
If theTRANSFORMclausewas used in theCREATE MODELstatement that created the model,ML.FEATURE_IMPORTANCEreturns the information of the pre-transform columns
from thequery_statementclause of theCREATE MODELstatement.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[[["\u003cp\u003e\u003ccode\u003eML.FEATURE_IMPORTANCE\u003c/code\u003e is a function that provides a feature importance score, indicating the usefulness of each feature in boosted tree or random forest models.\u003c/p\u003e\n"],["\u003cp\u003eThe function's syntax requires specifying the model with the project ID, dataset, and model name within the \u003ccode\u003eML.FEATURE_IMPORTANCE(MODEL 'project_id.dataset.model')\u003c/code\u003e format.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eML.FEATURE_IMPORTANCE\u003c/code\u003e returns four columns: \u003ccode\u003efeature\u003c/code\u003e, \u003ccode\u003eimportance_weight\u003c/code\u003e, \u003ccode\u003eimportance_gain\u003c/code\u003e, and \u003ccode\u003eimportance_cover\u003c/code\u003e, providing detailed information about each feature's contribution.\u003c/p\u003e\n"],["\u003cp\u003eIt is only compatible with boosted tree and random forest models, and it requires specific IAM permissions, \u003ccode\u003ebigquery.models.create\u003c/code\u003e and \u003ccode\u003ebigquery.models.getData\u003c/code\u003e, to run.\u003c/p\u003e\n"]]],[],null,["# The ML.FEATURE_IMPORTANCE function\n==================================\n\nThis document describes the `ML.FEATURE_IMPORTANCE` function, which lets you\nsee the feature importance score. This score indicates how useful or valuable\neach feature was in the construction of a boosted tree or a random forest model\nduring training. For more information, see the\n[`feature_importances` property](https://xgboost.readthedocs.io/en/latest/python/python_api.html?#xgboost.XGBRegressor.feature_importances_)\nin the XGBoost library.\n\nSyntax\n------\n\n```sql\nML.FEATURE_IMPORTANCE(\n MODEL `PROJECT_ID.DATASET.MODEL`\n)\n```\n\n### Arguments\n\n`ML.FEATURE_IMPORTANCE` takes the following arguments:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: your project ID.\n- \u003cvar translate=\"no\"\u003eDATASET\u003c/var\u003e: the BigQuery dataset that contains the model.\n- \u003cvar translate=\"no\"\u003eMODEL\u003c/var\u003e: the name of the model.\n\nOutput\n------\n\n`ML.FEATURE_IMPORTANCE` returns the following columns:\n\n- `feature`: a `STRING` value that contains the name of the feature column in the input training data.\n- `importance_weight`: a `FLOAT64` value that contains the number of times a feature is used to split the data across all trees.\n- `importance_gain`: a `FLOAT64` value that contains the average gain across all splits the feature is used in.\n- `importance_cover`: a `FLOAT64` value that contains the average coverage across all splits the feature is used in.\n\nIf the [`TRANSFORM` clause](/bigquery/docs/reference/standard-sql/bigqueryml-syntax-create#transform)\nwas used in the `CREATE MODEL` statement that created the model,\n`ML.FEATURE_IMPORTANCE` returns the information of the pre-transform columns\nfrom the `query_statement` clause of the `CREATE MODEL` statement.\n\nPermissions\n-----------\n\nYou must have the `bigquery.models.create` and `bigquery.models.getData`\n[Identity and Access Management (IAM) permissions](/bigquery/docs/access-control#bq-permissions)\nin order to run `ML.FEATURE_IMPORTANCE`.\n\nLimitations\n-----------\n\n`ML.FEATURE_IMPORTANCE` is only supported with\n[boosted tree models](/bigquery/docs/reference/standard-sql/bigqueryml-syntax-create-boosted-tree)\nand\n[random forest models](/bigquery/docs/reference/standard-sql/bigqueryml-syntax-create-random-forest).\n\nExample\n-------\n\nThis example retrieves feature importance from `mymodel` in\n`mydataset`. The dataset is in your default project. \n\n```sql\nSELECT\n *\nFROM\n ML.FEATURE_IMPORTANCE(MODEL `mydataset.mymodel`)\n```\n\nWhat's next\n-----------\n\n- For information about Explainable AI, see [BigQuery Explainable AI overview](/bigquery/docs/reference/standard-sql/bigqueryml-syntax-xai-overview).\n- For information about the supported SQL statements and functions for each model type, see [End-to-end user journey for each model](/bigquery/docs/e2e-journey)."]]
