일괄 SQL 변환기를 사용하여 코드 마이그레이션

이 문서에서는 BigQuery의 일괄 SQL 변환기를 사용하여 다른 SQL 언어로 작성된 스크립트를 GoogleSQL 쿼리로 변환하는 방법을 설명합니다. 이 문서는 Google Cloud 콘솔에 익숙한 사용자를 대상으로 합니다.

일괄 SQL 변환기는 BigQuery Migration Service의 일부입니다. 일괄 SQL 변환기를 통해 GoogleSQL로 변환할 수 있는 SQL 언어:

Amazon Redshift SQL
Apache HiveQL 및 Beeline CLI
IBM Netezza SQL 및 NZPLSQL
Teradata 및 Teradata Vantage
- SQL
- Basic Teradata Query(BTEQ)
- Teradata Parallel Transport(TPT)

또한 미리보기에서 다음 SQL 언어 변환이 지원됩니다.

Apache Spark SQL
Azure Synapse T-SQL
MySQL SQL
Oracle SQL, PL/SQL, Exadata
PostgreSQL SQL
Trino 또는 PrestoSQL
Snowflake SQL
SQL Server T-SQL
SQLite
Vertica SQL

필수 권한

BigQuery Migration Service를 사용 설정하려면 프로젝트에 대해 다음 권한이 있어야 합니다.

resourcemanager.projects.get
serviceusage.services.enable
serviceusage.services.get

BigQuery Migration Service를 액세스하고 사용하려면 프로젝트에 대해 다음 권한이 필요합니다.

bigquerymigration.workflows.create
bigquerymigration.workflows.get
bigquerymigration.workflows.list
bigquerymigration.workflows.delete
bigquerymigration.subtasks.get
bigquerymigration.subtasks.list

또는 다음 역할을 사용하여 동일한 권한을 얻을 수 있습니다.
- bigquerymigration.viewer - 읽기 전용 액세스
- bigquerymigration.editor - 읽기/쓰기 액세스

입력 및 출력 파일에 대해 Cloud Storage 버킷에 액세스하려면 다음 권한이 있어야 합니다.

소스 Cloud Storage 버킷에서 storage.objects.get
소스 Cloud Storage 버킷에서 storage.objects.list
대상 Cloud Storage 버킷에서 storage.objects.create

다음 역할에서 위에 표시된 모든 필요한 Cloud Storage 권한을 지정할 수 있습니다.

roles/storage.objectAdmin
roles/storage.admin

위치

일괄 SQL 변환기는 다음 처리 위치에서 사용할 수 있습니다.

us미국(멀티 리전)
euEU(멀티 리전)
southamerica-east1(상파울루)
us-central1(아이오와)
asia-northeast1(도쿄)
asia-south1(뭄바이)
asia-southeast1(싱가포르)
australia-southeast1(시드니)
europe-central2(바르샤바)
europe-north1(핀란드)
europe-west1(벨기에)
europe-west2(런던)
europe-west3(프랑크푸르트)

시작하기 전에

변환 작업을 제출하기 전에 다음 단계를 완료하세요.

BigQuery Migration API를 사용 설정합니다.
변환할 SQL 스크립트와 쿼리가 포함된 소스 파일을 수집합니다.
(선택사항) 메타데이터 파일을 만들어 변환의 정확도를 높입니다.
(선택사항) 소스 파일의 SQL 객체 이름을 BigQuery의 새 이름으로 매핑해야 하는지 결정합니다. 필요한 경우 사용할 이름 매핑 규칙을 결정합니다.
변환 작업을 제출하는 데 사용할 메서드를 결정합니다.
Cloud Storage에 소스 파일 업로드

BigQuery Migration API 사용 설정

Google Cloud CLI 프로젝트가 2022년 2월 15일 이전에 생성된 경우 다음과 같이 BigQuery Migration API를 사용 설정합니다.

Google Cloud 콘솔에서 BigQuery Migration API 페이지로 이동합니다.

BigQuery Migration API로 이동
사용 설정을 클릭합니다.

소스 파일 수집

소스 파일은 소스 언어에 유효한 SQL이 포함된 텍스트 파일이어야 합니다. 소스 파일에는 주석이 포함될 수도 있습니다. 사용 가능한 모든 방법을 사용하여 SQL이 유효한지 확인합니다.

메타데이터 파일 만들기

서비스에서 보다 정확한 변환 결과를 생성할 수 있도록 메타데이터 파일을 제공하는 것이 좋습니다. 그러나 필수는 아닙니다.

dwh-migration-dumper 명령줄 추출 도구를 사용하여 메타데이터 정보를 생성하거나 사용자의 자체 메타데이터 파일을 제공하면 됩니다. 메타데이터 파일이 준비되면 변환 소스 폴더에 소스 파일과 함께 포함할 수 있습니다. 변환기는 자동으로 메타데이터를 감지하고 소스 파일을 변환하는 데 활용하므로 이를 사용 설정하기 위해 추가 설정을 구성할 필요가 없습니다.

dwh-migration-dumper 도구를 사용하여 메타데이터 정보를 생성하려면 변환용 메타데이터 생성을 참조하세요.

자체 메타데이터를 제공하려면 소스 시스템의 SQL 객체에 대한 데이터 정의 언어(DDL) 문을 별도의 텍스트 파일로 수집합니다.

SQL 객체 이름 매핑

일괄 변환 중에 출력 이름 매핑을 선택적으로 수행할 수 있습니다. 출력 이름 매핑을 사용할 때 소스 시스템의 SQL 객체 이름을 BigQuery의 새 이름으로 변경하는 이름 매핑 규칙을 지정합니다. 예를 들어 소스 시스템에 schema1.table1 객체가 있고 BigQuery에서 이 객체 이름을 project1.dataset1.table1로 지정할 수 있습니다. 출력 이름 매핑을 사용하는 경우 일괄 변환 작업을 시작하기 전에 이름 매핑 규칙을 정의해야 합니다. 작업을 구성할 때 이러한 규칙을 수동으로 입력하거나 대신 이름 매핑 규칙이 포함된 JSON 파일을 만들어 업로드할 수 있습니다.

변환 작업 제출 방법 결정

일괄 변환 작업을 제출하는 방법은 3가지입니다.

일괄 변환 클라이언트: 구성 파일에서 설정을 변경하여 작업을 구성하고 명령줄을 사용하여 작업을 제출합니다. 이 방식에서는 소스 파일을 수동으로 Cloud Storage에 업로드할 필요가 없습니다. 클라이언트는 변환 작업을 처리하는 동안 여전히 Cloud Storage를 사용하여 파일을 저장합니다.

일괄 변환 클라이언트는 오픈소스 Python 클라이언트이며 이를 사용하면 로컬 머신에 있는 소스 파일을 변환하고 변환된 파일을 로컬 디렉터리로 출력할 수 있습니다. 구성 파일에서 몇 가지 설정을 변경하여 클라이언트를 기본 용도로 구성합니다. 원하는 경우 클라이언트에서 매크로 대체, 변환 입력과 출력의 사전 및 사후 처리와 같은 더욱 복잡한 태스크를 처리하도록 구성할 수도 있습니다. 자세한 내용은 일괄 변환 클라이언트 리드미를 참조하세요.
Google Cloud 콘솔: 사용자 인터페이스를 사용하여 작업을 구성하고 제출합니다. 이 방식을 사용하려면 소스 파일을 Cloud Storage에 업로드해야 합니다.
BigQuery Migration API: 프로그래매틱 방식으로 작업을 구성하고 제출합니다. 이 방식을 사용하려면 소스 파일을 Cloud Storage에 업로드해야 합니다.

구성 YAML 파일 만들기

선택적으로 구성 YAML 파일 구성을 만들고 사용해서 일괄 변환을 맞춤설정할 수 있습니다. 이러한 파일은 여러 방식으로 변환 출력을 변환하는 데 사용할 수 있습니다. 예를 들어 변환 중 SQL 객체의 대소문자를 변경하도록 구성 YAML 파일을 만들 수 있습니다.

일괄 변환 작업에 Google Cloud 콘솔 또는 BigQuery Migration API를 사용하려면 소스 파일이 포함된 Cloud Storage 버킷에 구성 YAML 파일을 업로드하면 됩니다.

일괄 변환 클라이언트를 사용하려면 구성 YAML 파일을 로컬 변환 입력 폴더에 배치하면 됩니다.

Cloud Storage에 입력 파일 업로드

Google Cloud 콘솔 또는 BigQuery Migration API를 사용하여 변환 작업을 수행하려면 Cloud Storage로 변환할 쿼리와 스크립트가 포함된 소스 파일을 업로드해야 합니다. 모든 메타데이터 파일 또는 구성 YAML 파일을 소스 파일이 포함된 동일한 Cloud Storage 버킷에 업로드할 수도 있습니다. 버킷 생성 및 Cloud Storage에 파일 업로드에 대한 자세한 내용은 버킷 만들기 및 파일 시스템에서 객체 업로드를 참조하세요.

변환 작업 제출

변환 작업을 시작하고, 진행 상황을 확인하고, 결과를 확인하려면 다음 단계를 따르세요.

일괄 변환 클라이언트

일괄 변환 클라이언트 및 Google Cloud CLI를 설치합니다.
gcloud CLI 사용자 인증 정보 파일을 생성합니다.
일괄 변환 클라이언트 설치 디렉터리에서 원하는 텍스트 편집기를 사용하여 config.yaml 파일을 열고 다음 설정을 수정합니다.
- project_number: 일괄 변환 작업에 사용할 프로젝트의 프로젝트 번호를 입력합니다. 프로젝트의 Google Cloud 콘솔 시작 페이지에 있는 프로젝트 정보 창에서 찾을 수 있습니다.
- gcs_bucket: 일괄 변환 클라이언트가 변환 작업 처리 중에 파일을 저장하는 데 사용할 Cloud Storage 버킷의 이름을 입력합니다.
- input_directory: 소스 파일과 모든 메타데이터 파일이 있는 디렉터리의 절대 또는 상대 경로를 입력합니다.
- output_directory: 변환된 파일의 대상 디렉터리에 대한 절대 또는 상대 경로를 입력합니다.
변경사항을 저장하고 config.yaml 파일을 닫습니다.
소스 파일과 메타데이터 파일을 입력 디렉터리에 저장합니다.
다음 명령어를 사용하여 일괄 변환 클라이언트를 실행합니다.
```
bin/dwh-migration-client
```
변환 작업이 생성되면 Google Cloud 콘솔의 변환 작업 목록에서 상태를 확인할 수 있습니다.
(선택사항) 변환 작업이 완료되면 스토리지 비용이 방지되도록 작업이 지정한 Cloud Storage 버킷에 만든 파일을 삭제합니다.

콘솔

이러한 단계에서는 소스 파일이 Cloud Storage 버킷에 이미 업로드되었다고 가정합니다.

Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

BigQuery로 이동
탐색 패널의 마이그레이션 섹션에서 SQL 변환을 클릭합니다.
변환 시작을 클릭합니다.
변환 구성 대화상자를 입력합니다.
1. 표시 이름에 변환 작업 이름을 입력합니다. 이름에는 문자, 숫자 또는 밑줄을 사용할 수 있습니다.
2. 처리 위치에서 변환 작업을 실행할 위치를 선택합니다. 예를 들어 개발자가 유럽에 있고 데이터가 위치 경계를 넘어가지 않게 하려면 eu 리전을 선택합니다. 변환 작업은 소스 파일 버킷과 동일한 위치를 선택할 때 최고의 성능을 발휘합니다.
3. 소스 언어에서 변환할 SQL 언어를 선택합니다.
4. 대상 언어에서 BigQuery를 선택합니다.
다음을 클릭합니다.
소스 위치에 변환할 파일이 포함된 Cloud Storage 폴더의 경로를 지정합니다. 경로를 bucket_name/folder_name/ 형식으로 입력하거나 찾아보기 옵션을 사용할 수 있습니다.
다음을 클릭합니다.
대상 위치에서 변환된 파일의 대상 Cloud Storage 폴더 경로를 지정합니다. 경로를 bucket_name/folder_name/ 형식으로 입력하거나 찾아보기 옵션을 사용할 수 있습니다.
기본 객체 이름이나 소스-대상 이름 매핑을 지정할 필요가 없는 변환을 수행하는 경우 11단계로 건너뜁니다. 그렇지 않으면 다음을 클릭합니다.
필요한 설정(선택사항)을 입력합니다.
1. (선택사항) 기본 데이터베이스에 소스 파일에서 사용할 기본 데이터베이스 이름을 입력합니다. 변환기는 이 기본 데이터베이스 이름을 사용하여 데이터베이스 이름이 누락된 SQL 객체의 정규화된 이름을 확인합니다.
2. (선택사항) 스키마 검색 경로의 경우, 변환기가 스키마 이름이 누락된 소스 파일에서 SQL 객체의 정규화된 이름을 확인해야 하는 경우에 검색할 스키마를 지정합니다. 소스 파일에서 여러 스키마 이름을 사용하는 경우 스키마 이름 추가를 클릭하고 참조될 수 있는 각 스키마의 값을 추가합니다.
  
  변환기는 제공된 메타데이터 파일을 검색하여 스키마 이름으로 테이블의 유효성을 검사합니다. 메타데이터에서 명확한 옵션을 결정할 수 없으면 입력한 첫 번째 스키마 이름이 기본값으로 사용됩니다. 기본 스키마 이름이 사용되는 방법에 대한 자세한 내용은 기본 스키마를 참조하세요.
3. (선택사항) 변환 중에 소스 시스템과 BigQuery 간에 SQL 객체 이름을 변경하도록 이름 매핑 규칙을 지정하려면 이름 매핑 쌍이 있는 JSON 파일을 제공하거나 Google Cloud 콘솔을 사용하여 매핑할 값을 지정하면 됩니다.
  
  JSON 파일을 사용하려면 다음 안내를 따르세요.
  1. 이름 매핑용 JSON 파일 업로드를 클릭합니다.
  2. 적절한 형식으로 된 이름 매핑 파일의 위치를 찾아 선택하고 열기를 클릭합니다.
    
    파일 크기는 5MB 미만이어야 합니다.
  Google Cloud 콘솔을 사용하려면 다음 안내를 따르세요.
  1. 이름 매핑 쌍 추가를 클릭합니다.
  2. 소스 열의 데이터베이스, 스키마, 관계, 속성 필드에 소스 객체 이름의 적절한 부분을 추가합니다.
  3. 대상 열의 필드에 BigQuery의 대상 객체 이름 부분을 추가합니다.
  4. 유형에 매핑하려는 객체를 설명하는 객체 유형을 선택합니다.
  5. 필요한 이름 매핑 쌍을 모두 지정할 때까지 1~4단계를 반복합니다. Google Cloud 콘솔을 사용할 때 이름 매핑 쌍을 최대 25개까지만 지정할 수 있습니다.
만들기를 클릭하여 변환 작업을 시작합니다.

변환 작업이 생성되면 변환 작업 목록에서 상태를 확인할 수 있습니다.

API

projects.locations.workflows.create 메서드에 지원되는 태스크 유형으로 MigrationWorkflow 리소스의 인스턴스를 제공합니다.

지원되는 태스크 유형

Amazon Redshift SQL - Redshift2BigQuery_Translation
Apache HiveQL 및 Beeline CLI - HiveQL2BigQuery_Translation
IBM Netezza SQL 및 NZPLSQL - Netezza2BigQuery_Translation
Teradata 및 Teradata Vantage - Teradata2BigQuery_Translation
Apache Spark SQL - SparkSQL2BigQuery_Translation
Azure Synapse T-SQL - AzureSynapse2BigQuery_Translation
MySQL SQL - MySQL2BigQuery_Translation
Oracle SQL, PL/SQL, Exadata - Oracle2BigQuery_Translation
PostgreSQL SQL - Postgresql2BigQuery_Translation
Presto 또는 Trino SQL - Presto2BigQuery_Translation
Snowflake SQL - Snowflake2BigQuery_Translation
SQL Server T-SQL - SQLServer2BigQuery_Translation
Vertica SQL - Vertica2BigQuery_Translation

제한사항

통합 변환 API는 1.5시간 이내에 완료되는 변환 작업만 지원합니다.

필수 권한

통합 변환 API를 사용하여 변환 작업을 만드는 데 필요한 권한을 얻으려면 관리자에게 parent 리소스에 대한 MigrationWorkflow 편집자(roles/bigquerymigration.editor) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 통합 변환 API를 사용하여 변환 작업을 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

통합 변환 API를 사용하여 변환 작업을 만들려면 다음 권한이 필요합니다.

bigquerymigration.workflows.create
bigquerymigration.workflows.get

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

예시: 일괄 변환 만들기

다음 curl 명령어는 입력 및 출력 파일이 Cloud Storage에 저장되는 일괄 변환 작업을 만듭니다. source_target_mapping 필드에는 소스 literal 항목을 대상 출력에 대한 선택적 상대 경로로 매핑하는 목록이 포함됩니다.

curl -d "{
  \"tasks\": {
     string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
           \"target_base_uri\": \"TARGET_BASE\",
           \"source_target_mapping\": {
              \"source_spec\": {
                 \"base_uri\": \"BASE\"
              }
           },
        }
     }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

다음을 바꿉니다.

TYPE: 소스 및 대상 언어를 결정하는 변환의 태스크 유형입니다.
TARGET_BASE: 모든 변환 출력에 대한 기본 URI입니다.
BASE: 변환 소스로 읽는 모든 파일의 기본 URI입니다.
TOKEN: 인증용 토큰입니다. 토큰을 생성하려면 gcloud auth print-access-token 명령어 또는 OAuth 2.0 Playground(https://www.googleapis.com/auth/cloud-platform 범위 사용)를 사용합니다.
PROJECT_ID: 변환을 처리할 프로젝트입니다.
LOCATION: 변환을 처리할 프로젝트의 위치입니다.

위 명령어는 projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID 형식으로 작성된 워크플로 ID가 포함된 응답을 반환합니다. API를 통해 변환 결과를 보려면 통합 변환 API 결과를 참조하세요.

예시: 문자열 리터럴 입력 및 출력으로 변환 작업 만들기

다음 curl 명령어는 문자열 리터럴 입력과 출력을 사용하여 변환 작업을 만듭니다. source_target_mapping 필드에는 소스 디렉터리를 대상 출력에 대한 선택적 상대 경로에 매핑하는 목록이 포함됩니다.

curl -d "{
  \"tasks\": {
     string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
        \"source_target_mapping\": {
           \"source_spec\": {
              \"literal\": {
              \"relative_path\": \"PATH\",
              \"literal_string\": \"STRING\"
              }
           }
        },
        \"target_return_literals\": \"TARGETS\",
        }
     }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

다음을 바꿉니다.

TYPE: 소스 및 대상 언어를 결정하는 변환의 태스크 유형입니다.
PATH: 파일 이름 또는 경로와 유사한 리터럴 항목의 식별자입니다.
STRING: 변환할 리터럴 입력 데이터(예: SQL)의 문자열입니다.
TARGETS: 사용자가 literal 형식의 응답으로 직접 반환되기를 원하는 예상 대상입니다. 이는 대상 URI 형식이어야 합니다(예: GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). 이 목록에 없는 항목은 응답으로 반환되지 않습니다. 일반 SQL 변환을 위한 생성된 디렉터리 GENERATED_DIR은 sql/입니다.
TOKEN: 인증용 토큰입니다. 토큰을 생성하려면 gcloud auth print-access-token 명령어 또는 OAuth 2.0 Playground(https://www.googleapis.com/auth/cloud-platform 범위 사용)를 사용합니다.
PROJECT_ID: 변환을 처리할 프로젝트입니다.
LOCATION: 변환을 처리할 프로젝트의 위치입니다.

변환 출력 살펴보기

변환 작업을 실행하면 Google Cloud 콘솔에서 작업에 대한 정보를 확인할 수 있습니다. Google Cloud 콘솔을 사용하여 작업을 실행한 경우 지정한 대상 Cloud Storage 버킷에서 작업 결과를 확인할 수 있습니다. 통합된 변환 API를 사용하여 작업을 실행한 경우 워크플로 ID와 함께 다른 명령어를 실행하여 작업 결과를 가져올 수 있습니다. 일괄 변환 클라이언트를 사용하여 작업을 실행한 경우 지정한 출력 디렉터리에서 작업 결과를 확인할 수 있습니다. 일괄 SQL 변환기는 다음 파일을 지정된 대상으로 출력합니다.

변환된 파일
CSV 형식의 변환 요약 보고서
JSON 형식의 사용된 출력 이름 매핑

Google Cloud 콘솔 출력

변환 작업 세부정보를 보려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

BigQuery로 이동
탐색 패널의 마이그레이션 섹션에서 SQL 변환을 클릭합니다.
변환 작업 목록에서 변환 세부정보를 보려는 작업을 찾습니다. 그런 다음 변환 작업 이름을 클릭합니다.
결과 섹션에서는 전체 변환 성공률, 처리된 문 수, 작업 기간을 확인할 수 있습니다.
로그 요약 탭을 선택하여 문제 카테고리, 추천 작업, 각 문제가 발생한 빈도를 포함한 변환 문제 요약을 확인합니다. 또한 문제 카테고리를 선택하여 해당 문제 카테고리와 연결된 로그 메시지를 볼 수 있습니다(미리보기).
로그 메시지 탭을 선택하여 문제 카테고리, 특정 문제 메시지, 문제가 발생한 파일 링크를 포함하여 각 변환 문제에 대한 자세한 내용을 확인합니다. 로그 메시지 탭에서 문제를 선택하여 적용 가능한 경우 입력 및 출력 파일을 표시하는 코드 탭을 열 수 있습니다(미리보기).
변환 구성 탭을 선택하여 변환 작업 구성 세부정보를 확인합니다.

통합된 변환 API 결과

비동기 변환이 완료된 후 다음 명령어를 사용해서 변환 작업 워크플로 ID를 지정하여 결과를 가져옵니다.

curl \
-H "Content-Type:application/json" \
-H "Authorization:Bearer TOKEN" -X GET https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

다음을 바꿉니다.

TOKEN: 인증용 토큰입니다. 토큰을 생성하려면 gcloud auth print-access-token 명령어 또는 OAuth 2.0 Playground(https://www.googleapis.com/auth/cloud-platform 범위 사용)를 사용합니다.
PROJECT_ID: 변환을 처리할 프로젝트입니다.
LOCATION: 변환을 처리할 프로젝트의 위치입니다.
WORKFLOW_ID: 변환 워크플로를 만들 때 생성된 ID입니다.

요약 보고서

요약 보고서는 변환 작업 중에 발생한 모든 경고 및 오류 메시지 테이블을 포함하는 CSV 파일입니다.

Google Cloud 콘솔에서 요약 파일을 보려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

BigQuery로 이동
탐색 패널의 마이그레이션 섹션에서 SQL 변환을 클릭합니다.
변환 작업 목록에서 원하는 작업을 찾고 상태 열에서 세부정보 표시를 클릭합니다.
변환 보고서 섹션에서 batch_translation_report.csv를 클릭합니다.
객체 세부정보 페이지에서 인증된 URL 행의 값을 클릭하여 브라우저에서 파일을 확인합니다.

다음 테이블에서는 요약 파일 열을 설명합니다.

열	설명
타임스탬프	문제가 발생한 타임스탬프입니다.
FilePath	문제와 연결된 소스 파일의 경로입니다.
파일 이름	문제와 연결된 소스 파일의 이름입니다.
ScriptLine	문제가 발생한 줄 번호입니다.
ScriptColumn	문제가 발생한 열 번호입니다.
TranspilerComponent	경고나 오류가 발생한 변환 엔진 내부 구성요소입니다. 이 열은 비어 있을 수 있습니다.
환경	경고 또는 오류와 관련된 변환 언어 환경입니다. 이 열은 비어 있을 수 있습니다.
ObjectName	경고 또는 오류와 관련된 소스 파일의 SQL 객체입니다. 이 열은 비어 있을 수 있습니다.
심각도	문제 심각도로, 경고나 오류입니다.
카테고리	변환 문제 카테고리입니다.
SourceType	이 문제의 원인입니다. 이 열의 값은 입력 SQL 파일의 문제를 나타내는 `SQL` 또는 메타데이터 패키지의 문제를 나타내는 `METADATA`일 수 있습니다.
메시지	변환 문제 경고 또는 오류 메시지입니다.
ScriptContext	문제와 연결된 소스 파일의 SQL 스니펫입니다.
작업	문제를 해결하기 위한 권장한 조치입니다.

코드 탭

코드 탭을 사용하면 특정 변환 작업의 입력 및 출력 파일에 대한 자세한 정보를 검토할 수 있습니다. 코드 탭에서 변환 작업에 사용되는 파일을 조사하고, 입력 파일과 번역의 부정확성을 나란히 비교하고, 로그 요약과 메시지를 볼 수 있습니다. 변경할 수 있습니다.

코드 탭에 액세스하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

BigQuery로 이동
탐색 패널의 마이그레이션 섹션에서 SQL 변환을 클릭합니다.
변환 작업 목록에서 원하는 작업을 찾은 후에 상태 열에서 세부정보 표시를 클릭합니다.
코드 탭을 선택합니다.

소비된 출력 이름 매핑 파일

이 JSON 파일에는 변환 작업에 사용된 출력 이름 매핑 규칙이 포함되어 있습니다. 이 파일의 규칙은 이름 매핑 규칙 충돌이나 변환 중에 식별된 SQL 객체에 대한 이름 매핑 규칙 부족으로 인해 변환 작업에 지정한 출력 이름 매핑 규칙과 다를 수 있습니다. 이 파일을 검토하여 이름 매핑 규칙을 수정해야 하는지 여부를 결정합니다. 수정한 경우 식별된 모든 문제를 해결하는 새로운 출력 이름 매핑 규칙을 만들고 새 변환 작업을 실행합니다.

변환된 파일

각 소스 파일에 대해 해당 출력 파일이 대상 경로에 생성됩니다. 출력 파일에는 변환된 쿼리가 포함됩니다.

대화형 SQL 변환기를 사용하여 일괄 변환된 SQL 쿼리 디버깅

BigQuery 대화형 SQL 변환기를 사용하여 소스 데이터베이스와 동일한 메타데이터 또는 객체 매핑 정보를 사용하여 SQL 쿼리를 검토하거나 디버깅할 수 있습니다. 일괄 변환 작업을 완료하면 BigQuery는 쿼리에 적용할 수 있는 작업 메타데이터, 객체 매핑 또는 스키마 검색 경로에 대한 정보가 포함된 변환 구성 ID를 생성합니다. 대화형 SQL 변환기와 일괄 변환 구성 ID를 사용하여 지정된 구성으로 SQL 쿼리를 실행합니다.

일괄 변환 구성 ID를 사용하여 대화형 SQL 변환을 시작하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

BigQuery로 이동
탐색 메뉴의 마이그레이션 섹션에서 SQL 변환을 클릭합니다.
변환 작업 목록에서 원하는 작업을 찾은 후 옵션 더보기 > 대화형 변환 열기를 클릭합니다.

이제 BigQuery 대화형 SQL 변환기가 해당 일괄 변환 구성 ID로 열립니다. 대화형 변환의 변환 구성 ID를 보려면 대화형 변환기에서 더보기 > 변환 설정을 클릭합니다.

제한사항

변환기는 SQL 이외의 언어에서 사용자 정의 함수(UDF)를 변환할 수 없습니다. 입력 및 출력 데이터 유형을 결정하기 위해 파싱할 수 없기 때문입니다. 이렇게 하면 이러한 UDF를 참조하는 SQL 문 변환이 부정확해질 수 있습니다. 변환 중에 SQL이 아닌 UDF를 올바르게 참조하게 하려면 유효한 SQL을 사용하여 동일한 서명으로 자리표시자 UDF를 만듭니다.

예를 들어 C로 작성된 UDF가 두 정수의 합을 계산한다고 가정해 보겠습니다. 이 UDF를 참조하는 SQL 문이 올바르게 변환되게 하려면 다음 예시와 같이 C UDF와 동일한 서명을 공유하는 자리표시자 SQL UDF를 만듭니다.

CREATE FUNCTION Test.MySum (a INT, b INT)
  RETURNS INT
  LANGUAGE SQL
  RETURN a + b;

이 자리표시자 UDF를 텍스트 파일로 저장하고 해당 파일을 변환 작업의 소스 파일 중 하나로 포함합니다. 이렇게 하면 변환기가 UDF 정의를 학습하고 예상 입력 및 출력 데이터 유형을 식별할 수 있습니다.

할당량 및 한도

BigQuery Migration API 할당량이 적용됩니다.
프로젝트마다 활성 변환 태스크를 최대 10개까지 있을 수 있습니다.
소스 파일과 메타데이터 파일의 총 수에는 엄격한 제한이 없지만 우수한 성능을 위해 파일 수를 1000개 미만으로 유지하는 것이 좋습니다.

변환 오류 문제 해결

`RelationNotFound` 또는 `AttributeNotFound` 변환 문제

변환은 메타데이터 DDL에서 가장 잘 작동합니다. SQL 객체 정의를 찾을 수 없으면 변환 엔진이 RelationNotFound 또는 AttributeNotFound 문제를 일으킵니다. 모든 객체 정의가 제공되도록 하려면 메타데이터 추출자를 사용해서 메타데이터 패키지를 생성하는 것이 좋습니다. 메타데이터 부족으로 인해 간접적으로 발생하는 많은 기타 오류를 해결할 수 있으므로, 대부분의 변환 오류를 해결하기 위해서는 우선 메타데이터를 추가하는 것이 좋습니다.

자세한 내용은 변환 및 평가를 위한 메타데이터 생성을 참조하세요.

가격 책정

일괄 SQL 변환기를 사용하는 데에는 요금이 부과되지 않습니다. 그러나 입력 및 출력 파일을 저장하는 데 사용되는 스토리지에는 일반 요금이 발생합니다. 자세한 내용은 스토리지 가격 책정을 참조하세요.

다음 단계

데이터 웨어하우스 마이그레이션의 다음 단계를 자세히 알아보세요.

일괄 SQL 변환기를 사용하여 코드 마이그레이션

필수 권한

위치

시작하기 전에

BigQuery Migration API 사용 설정

소스 파일 수집

메타데이터 파일 만들기

SQL 객체 이름 매핑

변환 작업 제출 방법 결정

구성 YAML 파일 만들기

Cloud Storage에 입력 파일 업로드

변환 작업 제출

일괄 변환 클라이언트

콘솔

API

지원되는 태스크 유형

제한사항

필수 권한

필수 권한

예시: 일괄 변환 만들기

예시: 문자열 리터럴 입력 및 출력으로 변환 작업 만들기

변환 출력 살펴보기

Google Cloud 콘솔 출력

통합된 변환 API 결과

요약 보고서

코드 탭

소비된 출력 이름 매핑 파일

변환된 파일

대화형 SQL 변환기를 사용하여 일괄 변환된 SQL 쿼리 디버깅

제한사항

할당량 및 한도

변환 오류 문제 해결

RelationNotFound 또는 AttributeNotFound 변환 문제

가격 책정

다음 단계

`RelationNotFound` 또는 `AttributeNotFound` 변환 문제