Stay organized with collections
Save and categorize content based on your preferences.
The ML.PRINCIPAL_COMPONENTS function
This document describes the ML.PRINCIPAL_COMPONENTS function, which lets you
see the principal components of a principal component analysis (PCA) model.
Principal components and
eigenvectors
are the same concepts in PCA models.
Syntax
ML.PRINCIPAL_COMPONENTS(
MODEL `PROJECT_ID.DATASET.MODEL`
)
Arguments
ML.PRINCIPAL_COMPONENTS takes the following arguments:
PROJECT_ID: your project ID.
DATASET: the BigQuery dataset that contains
the model.
MODEL: the name of the model.
Output
ML.PRINCIPAL_COMPONENTS returns the following columns:
principal_component_id: an INT64 that contains the principal
component ID.
feature: a STRING value that contains the feature column name.
numerical_value: a FLOAT64 value that contains the feature value for the
principal component that principal_component_id identifies if the column
identified by the feature value is numeric. Otherwise,
numerical_value is NULL.
categorical_value: an ARRAY<STRUCT> value that contains information
about categorical features. Each struct contains the following fields:
categorical_value.category: a STRING value that contains the name of
each category.
categorical_value.value: a FLOAT64 value that contains the value of
categorical_value.category for the principal component that
principal_component_id identifies.
The output is in descending order by the eigenvalues of the principal
components, which you can get by using the
ML.PRINCIPAL_COMPONENT_INFO function.
Example
The following example retrieves the principal components from the model
mydataset.mymodel in your default project:
[[["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-25 UTC."],[[["\u003cp\u003eThe \u003ccode\u003eML.PRINCIPAL_COMPONENTS\u003c/code\u003e function retrieves the principal components of a principal component analysis (PCA) model, which are the same as eigenvectors in PCA.\u003c/p\u003e\n"],["\u003cp\u003eThe function's syntax requires specifying the model's location using the project ID, dataset, and model name within the \u003ccode\u003eML.PRINCIPAL_COMPONENTS(MODEL \u003c/code\u003eproject_id.dataset.model\u003ccode\u003e)\u003c/code\u003e structure.\u003c/p\u003e\n"],["\u003cp\u003eThe output includes the principal component ID, feature name, numerical value (if applicable), and categorical value details, with categorical features stored as an array of structs.\u003c/p\u003e\n"],["\u003cp\u003eThe results are sorted in descending order by the eigenvalues of the principal components, which can be further retrieved using the \u003ccode\u003eML.PRINCIPAL_COMPONENT_INFO\u003c/code\u003e function.\u003c/p\u003e\n"],["\u003cp\u003eThe example provided shows the user how to retrieve principal components from their model using the function.\u003c/p\u003e\n"]]],[],null,["# The ML.PRINCIPAL_COMPONENTS function\n====================================\n\nThis document describes the `ML.PRINCIPAL_COMPONENTS` function, which lets you\nsee the principal components of a principal component analysis (PCA) model.\nPrincipal components and\n[eigenvectors](https://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors)\nare the same concepts in PCA models.\n\nSyntax\n------\n\n```sql\nML.PRINCIPAL_COMPONENTS(\n MODEL `PROJECT_ID.DATASET.MODEL`\n)\n```\n\n### Arguments\n\n`ML.PRINCIPAL_COMPONENTS` 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.PRINCIPAL_COMPONENTS` returns the following columns:\n\n- `principal_component_id`: an `INT64` that contains the principal component ID.\n- `feature`: a `STRING` value that contains the feature column name.\n- `numerical_value`: a `FLOAT64` value that contains the feature value for the principal component that `principal_component_id` identifies if the column identified by the `feature` value is numeric. Otherwise, `numerical_value` is `NULL`.\n- `categorical_value`: an `ARRAY\u003cSTRUCT\u003e` value that contains information\n about categorical features. Each struct contains the following fields:\n\n - `categorical_value.category`: a `STRING` value that contains the name of each category.\n - `categorical_value.value`: a `FLOAT64` value that contains the value of `categorical_value.category` for the principal component that `principal_component_id` identifies.\n\nThe output is in descending order by the eigenvalues of the principal\ncomponents, which you can get by using the\n[`ML.PRINCIPAL_COMPONENT_INFO` function](/bigquery/docs/reference/standard-sql/bigqueryml-syntax-principal-component-info).\n\nExample\n-------\n\nThe following example retrieves the principal components from the model\n`mydataset.mymodel` in your default project: \n\n```sql\nSELECT\n *\nFROM\n ML.PRINCIPAL_COMPONENTS(MODEL `mydataset.mymodel`)\n```\n\nWhat's next\n-----------\n\n- For information about model weights support in BigQuery ML, see [BigQuery ML model weights overview](/bigquery/docs/weights-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)."]]
