Manage models
This page shows you how to manage BigQuery ML models including copying
models and renaming models.
Rename models
Currently, you cannot change the name of an existing model. If you need to
change the model's name, follow the steps to
copy the model
. When
you 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 dataset
by:
- Using the Google Cloud console.
- Using the bq command-line tool's
bq cp
command.
- Calling the
jobs.insert
API method directly and configuring a
copy job
or 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 the
same naming conventions as when you
create a model
.
- Model copies are subject to BigQuery
limits
on copy jobs.
- Copying a model is not currently supported by the Google Cloud console.
- When copying models, the destination dataset must reside in the same location
as the dataset containing the model being copied. For example, you cannot copy
a model from an EU-based dataset and write it to a US-based dataset.
- 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 is
not currently supported.
Copy a model
You can copy a model by:
- Using the command-line tool's
bq cp
command
- Calling the
jobs.insert
API method and configuring a
copy job
or by using the client libraries
To copy a model:
Console
Currently, the Google Cloud console does not support copying models.
bq
Issue the
bq cp
command. Optional flags:
-f
or
--force
overwrites an existing model in the destination dataset
and doesn't prompt you for confirmation.
-n
or
--no_clobber
returns the following error message if the model
exists in the destination dataset:
'[PROJECT_ID]:[DATASET].[MODEL]'
already exists, skipping
.
If
-n
is not specified, the default behavior is to prompt you to choose
whether to replace the destination model.
If the source or destination dataset is in a project other than your default
project, add the project ID to the dataset names in the following format:
[PROJECT_ID]:[DATASET]
.
Supply the
--location
flag and set the value to your
location
.
bq --location=[LOCATION] cp -f -n [PROJECT_ID]:[DATASET].[SOURCE_MODEL] [PROJECT_ID]:[DATASET].[DESTINATION_MODEL]
Where:
[LOCATION]
is the name of your location. The
--location
flag is
optional. For example, if you are using BigQuery in the
Tokyo region, you can set the flag's value to
asia-northeast1
. You can
set a default value for the location using the
.bigqueryrc file
.
[PROJECT_ID]
is your project ID.
[DATASET]
is the name of the source or destination dataset.
[SOURCE_MODEL]
is the model you're copying.
[DESTINATION_MODEL]
is the name of the model in the destination dataset.
Examples:
Enter the following command to copy
mydataset.mymodel
to
mydataset2
. Both datasets are in your default project and were
created in the
US
multi-region location.
bq --location=US cp mydataset.mymodel mydataset2.mymodel
Enter the following command to copy
mydataset.mymodel
and to overwrite a
destination model with the same name. The source dataset is in your default
project. The destination dataset is in
myotherproject
. The
-f
shortcut is
used to overwrite the destination model without a prompt.
mydataset
and
myotherdataset
were created in the
US
multi-region location.
bq --location=US cp -f mydataset.mymodel myotherproject:myotherdataset.mymodel
Enter the following command to copy
mydataset.mymodel
and to return an error
if the destination dataset contains a model with the same name. The source
dataset is in your default project. The destination dataset is in
myotherproject
. The
-n
shortcut is used to prevent overwriting a model with
the same name. Both datasets were created in the
US
multi-region location.
bq --location=US cp -n mydataset.mymodel myotherproject:myotherdataset.mymodel
Enter the following command to copy
mydataset.mymodel
to
mydataset2
and
to rename the model
mymodel2
. Both datasets are in your default project.
Both datasets were created in the
asia-northeast1
region.
bq --location=asia-northeast1 cp mydataset.mymodel mydataset2.mymodel2
API
To copy a model by using the API, call the
bigquery.jobs.insert
method and configure a
copy
job. Specify your location in the
location
property in the
jobReference
section of the
job 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) to
encrypt a model, see
Use CMEK to protect BigQuery ML models
.
What's next