Manage models

This document shows you how to manage BigQuery ML models, includingcopying models and renaming models.

Required roles

To get the permissions that you need to read and create BigQuery models, ask your administrator to grant you theBigQuery Data Editor (roles/bigquery.dataEditor) IAM role on the project. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the permissions required to read and create BigQuery models. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to read and create BigQuery models:

  • To read information from models:bigquery.models.getData
  • To create models:bigquery.models.create

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Rename models

You cannot change the name of an existing model. If you need tochange the model's name, follow the steps tocopy the model. Whenyou specify the destination in the copy operation, use the new model name.

Copy models

You can copy one or more models from a source dataset to a destination datasetby:

  • Using the Google Cloud console.
  • Using the bq command-line tool'sbq cp command.
  • Calling thejobs.insertAPI method directly and configuring acopy jobor by using the client libraries.

Limitations on copying models

Model copy jobs are subject to the following limitations:

  • When you copy a model, the name of the destination model must adhere to thesame naming conventions as when youcreate a model.
  • Model copies are subject to BigQuerylimits on copy jobs.
  • Copying a model is not supported by the Google Cloud console.
  • Copying multiple source models in a single command is not supported.
  • When you copy a model by using the CLI, the--destination_kms_key flag isnot supported.

Copy a model

You can copy a model by:

  • Using the command-line tool'sbq cp command
  • Calling thejobs.insertAPI method and configuring acopy jobor by using the client libraries

To copy a model:

Console

The Google Cloud console does not support copying models.

bq

Issue thebq cp command. Optional flags:

  • -f or--force overwrites an existing model in the destination datasetand doesn't prompt you for confirmation.

  • -n or--no_clobber returns the following error message if the modelexists in the destination dataset:'[PROJECT_ID]:[DATASET].[MODEL]'already exists, skipping.

    If-n is not specified, the default behavior is to prompt you to choosewhether to replace the destination model.

Note: The--destination_kms_key flag is not supported when you copy amodel.

If the source or destination dataset is in a project other than your defaultproject, add the project ID to the dataset names in the following format:PROJECT_ID:DATASET.

Supply the--location flag and set the value to yourlocation.

bq--location=LOCATIONcp-f-nPROJECT_ID:DATASET.SOURCE_MODELPROJECT_ID:DATASET.DESTINATION_MODEL

Replace the following:

  • LOCATION:the name of your location. The--location flag isoptional. For example, if you are using BigQuery in theTokyo region, you can set the flag's value toasia-northeast1. You canset a default value for the location using the.bigqueryrc file.For a full list of locations, seeBigQuery locations.
  • PROJECT_ID: your project ID.
  • DATASET: the name of the source or destination dataset.
  • SOURCE_MODEL: the model you're copying.
  • DESTINATION_MODEL: the name of the model in the destination dataset.

Examples:

Enter the following command to copymydataset.mymodel tomydataset2.Both datasets are in your default project and werecreated in theUS multi-region location.

bq --location=US cp mydataset.mymodel mydataset2.mymodel

Enter the following command to copymydataset.mymodel and to overwrite adestination model with the same name. The source dataset is in your defaultproject. The destination dataset is inmyotherproject. The-f shortcut isused to overwrite the destination model without a prompt.mydataset andmyotherdataset were created in theUS multi-regionlocation.

bq --location=US cp -f mydataset.mymodel myotherproject:myotherdataset.mymodel

Enter the following command to copymydataset.mymodel and to return an errorif the destination dataset contains a model with the same name. The sourcedataset is in your default project. The destination dataset is inmyotherproject. The-n shortcut is used to prevent overwriting a model withthe same name.Bothdatasets were created in theUS multi-region location.

bq --location=US cp -n mydataset.mymodel myotherproject:myotherdataset.mymodel

Enter the following command to copymydataset.mymodel tomydataset2 andto rename the modelmymodel2. Both datasets are in your default project.Both datasets were created in theasia-northeast1 region.

bq --location=asia-northeast1 cp mydataset.mymodel mydataset2.mymodel2

API

To copy a model by using the API, call thebigquery.jobs.insertmethod and configure acopy job. Specify your location in thelocation property in thejobReference section of thejob resource.

You must specify the following values in your job configuration:

"copy": {      "sourceTable": {       // Required        "projectId": string, // Required        "datasetId": string, // Required        "tableId": string    // Required      },      "destinationTable": {  // Required        "projectId": string, // Required        "datasetId": string, // Required        "tableId": string    // Required      },      "createDisposition": string,  // Optional      "writeDisposition": string,   // Optional    },

Where:

  • sourceTable: provides information about the model to be copied.
  • destinationTable: provides information about the new model.
  • createDisposition:specifies whether to create the model if it doesn't exist.
  • writeDisposition:specifies whether to overwrite an existing model.

Encrypt models

For more information about using a customer-managed encryption key (CMEK) toencrypt a model, seeUse CMEK to protect BigQuery ML models.

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.