이 문서에서는 모델 복사 및 모델 이름 바꾸기를 포함하여 BigQuery ML 모델을 관리하는 방법을 설명합니다.
필요한 역할
BigQuery 모델을 읽고 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 BigQuery 데이터 편집자(roles/bigquery.dataEditor) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
이 사전 정의된 역할에는 BigQuery 모델을 읽고 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
LOCATION: 위치의 이름. --location 플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용하는 경우에는 플래그 값을 asia-northeast1로 설정할 수 있습니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
전체 위치 목록은 BigQuery 위치를 참조하세요.
PROJECT_ID: 프로젝트 ID
DATASET: 소스 또는 대상 데이터 세트의 이름
SOURCE_MODEL: 복사할 모델
DESTINATION_MODEL: 대상 데이터 세트의 모델 이름
예를 들면 다음과 같습니다.
mydataset.mymodel을 mydataset2로 복사하려면 다음 명령어를 입력합니다.
두 데이터 세트 모두 기본 프로젝트에 있고 US 멀티 리전 위치에서 생성되었습니다.
mydataset.mymodel을 복사하고 이름이 같은 대상 모델을 덮어쓰려면 다음 명령어를 입력합니다. 소스 데이터 세트는 기본 프로젝트에 있고, 대상 데이터 세트는 myotherproject에 있습니다. -f 단축키를 사용하면 확인 메시지 없이 대상 모델을 덮어쓸 수 있습니다.
mydataset와 myotherdataset는 US 멀티 리전 위치에서 생성되었습니다.
mydataset.mymodel을 복사하고 대상 데이터 세트에 이름이 같은 모델이 있는 경우에 오류를 반환하려면 다음 명령어를 입력합니다. 소스 데이터 세트는 기본 프로젝트에 있고, 대상 데이터 세트는 myotherproject에 있습니다. -n 단축키를 사용하면 이름이 같은 모델을 덮어쓰지 않습니다.
두 데이터 세트 모두 US 멀티 리전 위치에서 생성되었습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-19(UTC)"],[[["\u003cp\u003eThis document explains how to manage BigQuery ML models, focusing on copying and renaming models, as directly renaming existing models is not supported.\u003c/p\u003e\n"],["\u003cp\u003eTo read and create BigQuery models, users need the \u003ccode\u003ebigquery.models.getData\u003c/code\u003e and \u003ccode\u003ebigquery.models.create\u003c/code\u003e permissions, respectively, which are included in the \u003ccode\u003eroles/bigquery.dataEditor\u003c/code\u003e IAM role.\u003c/p\u003e\n"],["\u003cp\u003eModels can be copied to a destination dataset using the Google Cloud command-line tool (\u003ccode\u003ebq cp\u003c/code\u003e), API (\u003ccode\u003ejobs.insert\u003c/code\u003e), or client libraries, but not the Google Cloud console, and they must adhere to specific naming conventions.\u003c/p\u003e\n"],["\u003cp\u003eCopying models with the command-line tool (\u003ccode\u003ebq cp\u003c/code\u003e) supports options to overwrite (\u003ccode\u003e-f\u003c/code\u003e) or prevent overwriting (\u003ccode\u003e-n\u003c/code\u003e) existing models at the destination, but the \u003ccode\u003e--destination_kms_key\u003c/code\u003e flag is unsupported.\u003c/p\u003e\n"],["\u003cp\u003eWhile model renaming is not directly supported, it can be achieved by copying a model to a new destination and assigning it the desired name during the copy operation.\u003c/p\u003e\n"]]],[],null,["# Manage models\n=============\n\nThis document shows you how to manage BigQuery ML models, including\ncopying models and renaming models.\n\nRequired roles\n--------------\n\n\nTo get the permissions that\nyou need to read and create BigQuery models,\n\nask your administrator to grant you the\n\n\n[BigQuery Data Editor](/iam/docs/roles-permissions/bigquery#bigquery.dataEditor) (`roles/bigquery.dataEditor`)\nIAM role on the project.\n\n\nFor more information about granting roles, see [Manage access to projects, folders, and organizations](/iam/docs/granting-changing-revoking-access).\n\n\nThis predefined role contains\n\nthe permissions required to read and create BigQuery models. To see the exact permissions that are\nrequired, expand the **Required permissions** section:\n\n\n#### Required permissions\n\nThe following permissions are required to read and create BigQuery models:\n\n- To read information from models: ` ``bigquery.models.getData`\n- To create models: ` ``bigquery.models.create`\n\n\nYou might also be able to get\nthese permissions\nwith [custom roles](/iam/docs/creating-custom-roles) or\nother [predefined roles](/iam/docs/roles-overview#predefined).\n\nRename models\n-------------\n\nYou cannot change the name of an existing model. If you need to\nchange the model's name, follow the steps to [copy the model](#copy-model). When\nyou specify the destination in the copy operation, use the new model name.\n\nCopy models\n-----------\n\nYou can copy one or more models from a source dataset to a destination dataset\nby:\n\n- Using the Google Cloud console.\n- Using the bq command-line tool's `bq cp` command.\n- Calling the [jobs.insert](/bigquery/docs/reference/rest/v2/jobs/insert) API method directly and configuring a [copy job](/bigquery/docs/reference/rest/v2/Job#JobConfigurationTableCopy) or by using the client libraries.\n\n### Limitations on copying models\n\nModel copy jobs are subject to the following limitations:\n\n- When you copy a model, the name of the destination model must adhere to the same naming conventions as when you [create a model](/bigquery/docs/reference/standard-sql/bigqueryml-syntax-create#model_name).\n- Model copies are subject to BigQuery [limits](/bigquery/quotas#copy_jobs) on copy jobs.\n- Copying a model is not supported by the Google Cloud console.\n- Copying multiple source models in a single command is not supported.\n- When you copy a model by using the CLI, the `--destination_kms_key` flag is not supported.\n\n### Copy a model\n\nYou can copy a model by:\n\n- Using the command-line tool's `bq cp` command\n- Calling the [`jobs.insert`](/bigquery/docs/reference/rest/v2/jobs/insert) API method and configuring a [copy job](/bigquery/docs/reference/rest/v2/Job#JobConfigurationTableCopy) or by using the client libraries\n\nTo copy a model: \n\n### Console\n\nThe Google Cloud console does not support copying models.\n\n### bq\n\nIssue the `bq cp` command. Optional flags:\n\n- `-f` or `--force` overwrites an existing model in the destination dataset and doesn't prompt you for confirmation.\n- `-n` or `--no_clobber` returns the following error message if the model\n exists in the destination dataset: `'[PROJECT_ID]:[DATASET].[MODEL]'\n already exists, skipping`.\n\n If `-n` is not specified, the default behavior is to prompt you to choose\n whether to replace the destination model.\n\n| **Note:** The `--destination_kms_key` flag is not supported when you copy a model.\n\nIf the source or destination dataset is in a project other than your default\nproject, add the project ID to the dataset names in the following format:\n\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e`:`\u003cvar translate=\"no\"\u003eDATASET\u003c/var\u003e.\n\nSupply the\n`--location` flag and set the value to your\n[location](/bigquery/docs/locations). \n\n```bash\nbq --location=LOCATION cp -f -n PROJECT_ID:DATASET.SOURCE_MODEL PROJECT_ID:DATASET.DESTINATION_MODEL\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: 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](/bigquery/docs/bq-command-line-tool#setting_default_values_for_command-line_flags). For a full list of locations, see [BigQuery locations](/bigquery/docs/locations).\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: your project ID.\n- \u003cvar translate=\"no\"\u003eDATASET\u003c/var\u003e: the name of the source or destination dataset.\n- \u003cvar translate=\"no\"\u003eSOURCE_MODEL\u003c/var\u003e: the model you're copying.\n- \u003cvar translate=\"no\"\u003eDESTINATION_MODEL\u003c/var\u003e: the name of the model in the destination dataset.\n\nExamples:\n\nEnter the following command to copy `mydataset.mymodel` to\n`mydataset2`.\n\nBoth datasets are in your default project and were\ncreated in the `US` multi-region location. \n\n```\nbq --location=US cp mydataset.mymodel mydataset2.mymodel\n```\n\nEnter the following command to copy `mydataset.mymodel` and to overwrite a\ndestination model with the same name. The source dataset is in your default\nproject. The destination dataset is in `myotherproject`. The `-f` shortcut is\nused to overwrite the destination model without a prompt.\n`mydataset` and\n`myotherdataset` were created in the `US` multi-region\nlocation. \n\n```\nbq --location=US cp -f mydataset.mymodel myotherproject:myotherdataset.mymodel\n```\n\nEnter the following command to copy `mydataset.mymodel` and to return an error\nif the destination dataset contains a model with the same name. The source\ndataset is in your default project. The destination dataset is in\n`myotherproject`. The `-n` shortcut is used to prevent overwriting a model with\nthe same name.\nBoth\ndatasets were created in the `US` multi-region location. \n\n```\nbq --location=US cp -n mydataset.mymodel myotherproject:myotherdataset.mymodel\n```\n\nEnter the following command to copy `mydataset.mymodel` to `mydataset2` and\nto rename the model `mymodel2`. Both datasets are in your default project.\nBoth datasets were created in the `asia-northeast1` region. \n\n```\nbq --location=asia-northeast1 cp mydataset.mymodel mydataset2.mymodel2\n```\n\n### API\n\nTo copy a model by using the API, call the\n[`bigquery.jobs.insert`](/bigquery/docs/reference/rest/v2/jobs/insert)\nmethod and configure a `copy` job. Specify your location in the\n`location` property in the `jobReference` section of the\n[job resource](/bigquery/docs/reference/rest/v2/jobs).\n\nYou must specify the following values in your job configuration: \n\n```\n\"copy\": {\n \"sourceTable\": { // Required\n \"projectId\": string, // Required\n \"datasetId\": string, // Required\n \"tableId\": string // Required\n },\n \"destinationTable\": { // Required\n \"projectId\": string, // Required\n \"datasetId\": string, // Required\n \"tableId\": string // Required\n },\n \"createDisposition\": string, // Optional\n \"writeDisposition\": string, // Optional\n },\n```\n\nWhere:\n\n- `sourceTable`: provides information about the model to be copied.\n- `destinationTable`: provides information about the new model.\n- [createDisposition](/bigquery/docs/reference/rest/v2/Job#JobConfigurationTableCopy.FIELDS.create_disposition): specifies whether to create the model if it doesn't exist.\n- [writeDisposition](/bigquery/docs/reference/rest/v2/Job#JobConfigurationTableCopy.FIELDS.write_disposition): specifies whether to overwrite an existing model.\n\nEncrypt models\n--------------\n\nFor more information about using a customer-managed encryption key (CMEK) to\nencrypt a model, see\n[Use CMEK to protect BigQuery ML models](/bigquery/docs/customer-managed-encryption#cmek-bqml).\n\nWhat's next\n-----------\n\n- For an overview of BigQuery ML, see [Introduction to BigQuery ML](/bigquery/docs/bqml-introduction).\n- To get started using BigQuery ML, see [Create machine learning models in BigQuery ML](/bigquery/docs/create-machine-learning-model).\n- To learn more about working with models, see:\n - [Get model metadata](/bigquery/docs/getting-model-metadata)\n - [List models](/bigquery/docs/listing-models)\n - [Update model metadata](/bigquery/docs/updating-model-metadata)\n - [Delete models](/bigquery/docs/deleting-models)\n - [Manage models with Vertex AI](/bigquery/docs/managing-models-vertex)"]]
