Text of docs.cloud.google.com › bigquery › docs › batch-sql-translator as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Migrate code with the batch SQL translator | BigQuery | Google Cloud Documentation

Skip to main content Console English Deutsch Español Español – América Latina Français Indonesia Italiano Português Português – Brasil עברית 中文 – 简体 中文 – 繁體 日本語 한국어 Sign in BigQuery Start free Home Documentation Data analytics BigQuery Guides Stay organized with collections Save and categorize content based on your preferences. Migrate code with the batch SQL translator The batch SQL translator in BigQuery lets you translate scripts written in other SQL dialects into GoogleSQL queries in bulk.

You can submit and review the results of a batch translation job from the Google Cloud console, from the command line, or with the BigQuery Migration Service MCP server to accelerate large-scale workload migrations. To build a custom software integration, an automated CI/CD pipeline, or another programmatic workflow, call the BigQuery Migration API directly. For information about supported dialects and processing locations, see Supported SQL dialects and Locations .

Before you begin Before you submit a translation job, do the following steps. Enable SQL translations Enable the required API, and get the permissions needed to use a BigQuery SQL translator. For more information, see Enable SQL translations . Required permissions To get the permissions that you need to create translation jobs with the interactive translator, the translation API, or the batch SQL translator, ask your administrator to grant you the following IAM roles on the parent resource: Viewing and monitoring migration jobs: MigrationWorkflow Viewer ( roles/bigquerymigration.viewer ) Submitting migration jobs: MigrationWorkflow Editor ( roles/bigquerymigration.editor ) Access the Cloud Storage buckets for input and files: Storage Object Admin ( roles/storage.objectAdmin ) - on the source and destination Cloud Storage bucket.

For more information about granting roles, see Manage access to projects, folders, and organizations . These predefined roles contain the permissions required to create translation jobs with the interactive translator, the translation API, or the batch SQL translator. To see the exact permissions that are required, expand the Required permissions section: Required permissions The following permissions are required to create translation jobs with the interactive translator, the translation API, or the batch SQL translator: bigquerymigration.workflows.create bigquerymigration.workflows.get bigquerymigration.workflows.list bigquerymigration.workflows.delete bigquerymigration.subtasks.get bigquerymigration.subtasks.list storage.objects.get storage.objects.list storage.objects.create You might also be able to get these permissions with custom roles or other predefined roles .

To restrict specific translation workflow configurations in your organization, such as disallowing Gemini AI suggestions or restricting translation output types, configure Custom Org Policies for BigQuery Migration Service . Collect source files Source files must be text files that contain valid SQL for the source dialect. Source files can also include comments. Do your best to ensure the SQL is valid, using whatever methods are available to you.

Create metadata files To help the service generate more accurate translation results, we recommend that you provide metadata files. However, this isn't mandatory. You can use the dwh-migration-dumper command-line extraction tool to generate the metadata information. After you prepare the metadata files, you can include them along with the source files in the translation source folder. The translator automatically detects them and leverages them to translate source files, you don't need to configure any extra settings to enable this.

To generate metadata information by using the dwh-migration-dumper tool, see Generate metadata for translation . Create configuration YAML files You can optionally create and use configuration configuration YAML files to customize your batch translations. These files can be used to transform your translation output in various ways. For example, you can create a configuration YAML file to change the case of a SQL object during translation.

Use one of the following options to include a configuration YAML file in your translation job. Console Upload the configuration YAML file to the Cloud Storage directory that contains your source files . When you select that directory as an input location, the translation job includes the configuration YAML file automatically. gcloud The flags that you use with the gcloud alpha bq migration translate-batch command depend on where the configuration YAML file is stored: If the configuration YAML file is in the same directory as your source files, then you don't need any additional flags.

When you set that directory in the --source-gcs-uris or --source-local-dirs flag, the job includes the configuration YAML file automatically. If the configuration YAML file is stored separately on your local machine, then use the --source-local-files flag to upload it and add it to the job. If the configuration YAML file is stored separately in Cloud Storage, then use the --source-gcs-files flag to add it to the job. For example, the following command uploads your source files and a separately stored configuration YAML file from your local machine, and then runs the translation job: gcloud alpha bq migration translate-batch \ --source-dialect= SOURCE_DIALECT \ --target-dialect= TARGET_DIALECT \ --location= LOCATION \ --source-local-dirs= LOCAL_DIR = SOURCE_URI \ --source-local-files= LOCAL_CONFIG_YAML = CONFIG_YAML_URI \ --target-gcs-path= TARGET_URI Replace the following: LOCAL_CONFIG_YAML : the local path to the configuration YAML file, such as ./configs/change-case.config.yaml .

CONFIG_YAML_URI : the Cloud Storage URI that the command uploads the configuration YAML file to, such as gs://my_data_bucket/configs/change-case.config.yaml . This URI must be outside the SOURCE_URI directory. For descriptions of the other placeholders, see Submit a translation job . MCP Upload the configuration YAML file to the Cloud Storage directory that contains your source files . When you translate that directory with the translate_batch_queries tool , the translation job includes the configuration YAML file automatically.

If the configuration YAML file is stored in a separate Cloud Storage location outside your source directory, specify its Cloud Storage URI in your prompt. For more information, see Submit a translation job . Upload input files to Cloud Storage Upload the source files containing the queries and scripts that you want to translate to Cloud Storage. You can also upload any metadata files or configuration YAML files to the same Cloud Storage bucket and directory containing the source files.

For more information about creating buckets and uploading files to Cloud Storage, see Create buckets and Upload objects from a filesystem . Choose how to submit the translation job You have three options for submitting a batch translation job: Google Cloud console : Configure and submit a job using a user interface. This approach requires you to upload source files to Cloud Storage. Google Cloud CLI : Submit a job from the command line using the gcloud CLI.

The translate-batch command accepts your source and target locations as flags, and can upload local directories and files to Cloud Storage for you. For more information, see Submit a translation job . BigQuery Migration Service MCP server : Submit a job from an AI application or agent connected to the BigQuery Migration Service MCP server . This approach requires your source files to be in Cloud Storage. For more information, see Submit a translation job .

All options require your source files to be accessible in Cloud Storage, and all create the same kind of translation job. A job that you submit from the command line or from an MCP client still appears in the translation jobs list in the Google Cloud console. Submit a translation job Us

The rest of this page is on the live site.