List models

This page shows you how to list BigQuery ML models in a dataset. You canlist BigQuery ML models by:

  • Using the Google Cloud console.
  • Using thebq ls command in the bq command-line tool.
  • Calling themodels.listAPI method directly or by using the client libraries.

Required permissions

To list models in a dataset, you must be assigned theREADERrole on the dataset, or you must be assigned a project-level Identity and Access Management (IAM) role thatincludesbigquery.models.list permissions. If you are grantedbigquery.models.list permissions at the project level, you can list models inany dataset in the project. The following predefined, project-level IAM rolesincludebigquery.models.list permissions:

  • bigquery.dataViewer
  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.metadataViewer
  • bigquery.user
  • bigquery.admin

For more information on IAM roles and permissions in BigQuery ML,seeAccess control. For moreinformation on dataset-level roles, seeBasic roles for datasets.

List models

To list models in a dataset:

Console

  1. In the Google Cloud console, go to the BigQuery page.

    Go to the BigQuery page

  2. In the left pane, clickExplorer:

    Highlighted button for the Explorer pane.

    If you don't see the left pane, clickExpand left pane to open the pane.

  3. In theExplorer pane, expand your project and clickDatasets.

  4. Click the dataset that contains your model.

  5. Click theModels tab.

bq

Issue thebq ls command with the--models or-m flag. The--formatflag can be used to control the output. If you are listing modelsin a project other than your default project,add the project ID to the dataset in the following format:[PROJECT_ID]:[DATASET].

bq ls -m --format=prettyPROJECT_ID:DATASET

Replace the following:

  • PROJECT_ID is your project ID.
  • DATASET is the name of the dataset.

The command output looks like the following when the--format=pretty flagis used.--format=pretty produces formatted table output. TheModel Typecolumn displays the model type, for example,KMEANS.

+-------------------------+------------+--------+-----------------+|           Id            | Model Type | Labels |  Creation Time  |+-------------------------+------------+--------+-----------------+| mymodel                 | KMEANS     |        | 03 May 03:02:27 |+-------------------------+------------+--------+-----------------+

Examples:

Enter the following command to list models in datasetmydataset in yourdefault project.

bq ls --models --format=pretty mydataset

Enter the following command to list models in datasetmydataset inmyotherproject. This command uses the-m shortcut to list models.

bq ls -m --format=pretty myotherproject:mydataset

API

To list models by using the API, call themodels.listmethod and provide theprojectId anddatasetId.

Go

Before trying this sample, follow theGo setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryGo API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

import("context""fmt""io""cloud.google.com/go/bigquery""google.golang.org/api/iterator")// listModels demonstrates iterating through the collection of ML models in a dataset// and printing a basic identifier of the model.funclistModels(wio.Writer,projectID,datasetIDstring)error{// projectID := "my-project-id"// datasetID := "mydataset"ctx:=context.Background()client,err:=bigquery.NewClient(ctx,projectID)iferr!=nil{returnfmt.Errorf("bigquery.NewClient: %w",err)}deferclient.Close()fmt.Fprintf(w,"Models contained in dataset %q\n",datasetID)it:=client.Dataset(datasetID).Models(ctx)for{m,err:=it.Next()iferr==iterator.Done{break}iferr!=nil{returnerr}fmt.Fprintf(w,"Model: %s\n",m.FullyQualifiedName())}returnnil}

Java

Before trying this sample, follow theJava setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryJava API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

importcom.google.api.gax.paging.Page;importcom.google.cloud.bigquery.BigQuery;importcom.google.cloud.bigquery.BigQuery.ModelListOption;importcom.google.cloud.bigquery.BigQueryException;importcom.google.cloud.bigquery.BigQueryOptions;importcom.google.cloud.bigquery.Model;publicclassListModels{publicstaticvoidrunListModels(){// TODO(developer): Replace these variables before running the sample.StringdatasetName="MY_DATASET_NAME";listModels(datasetName);}publicstaticvoidlistModels(StringdatasetName){try{// Initialize client that will be used to send requests. This client only needs to be created// once, and can be reused for multiple requests.BigQuerybigquery=BigQueryOptions.getDefaultInstance().getService();Page<Model>models=bigquery.listModels(datasetName,ModelListOption.pageSize(100));if(models==null){System.out.println("Dataset does not contain any models.");return;}models.iterateAll().forEach(model->System.out.printf("Success! Model ID: %s",model.getModelId()));}catch(BigQueryExceptione){System.out.println("Models not listed in dataset due to error: \n"+e.toString());}}}

Node.js

Before trying this sample, follow theNode.js setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryNode.js API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

// Import the Google Cloud client libraryconst{BigQuery}=require('@google-cloud/bigquery');constbigquery=newBigQuery();asyncfunctionlistModels(){// Lists all existing models in the dataset./**   * TODO(developer): Uncomment the following lines before running the sample.   */// const datasetId = "my_dataset";constdataset=bigquery.dataset(datasetId);dataset.getModels().then(data=>{constmodels=data[0];console.log('Models:');models.forEach(model=>console.log(model.metadata));});}

Python

Before trying this sample, follow thePython setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryPython API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

fromgoogle.cloudimportbigquery# Construct a BigQuery client object.client=bigquery.Client()# TODO(developer): Set dataset_id to the ID of the dataset that contains#                  the models you are listing.# dataset_id = 'your-project.your_dataset'models=client.list_models(dataset_id)# Make an API request.print("Models contained in '{}':".format(dataset_id))formodelinmodels:full_model_id="{}.{}.{}".format(model.project,model.dataset_id,model.model_id)friendly_name=model.friendly_nameprint("{}: friendly_name='{}'".format(full_model_id,friendly_name))

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.