이 페이지는 Cloud Translation API를 통해 번역되었습니다.

대화형 SQL 변환기를 사용하여 쿼리 변환

이 문서에서는 BigQuery 대화형 SQL 변환기를 사용하여 다른 SQL 언어의 쿼리를 GoogleSQL 쿼리로 변환하는 방법을 설명합니다. 대화형 SQL 변환기를 사용하면 BigQuery로 워크로드를 마이그레이션할 때 드는 시간과 노력을 줄일 수 있습니다. 이 문서는 Google Cloud 콘솔에 익숙한 사용자를 대상으로 합니다.

사용자 위치가 지원되는 경우 변환 규칙 기능을 사용하여 대화형 SQL 변환기가 SQL을 변환하는 방법을 맞춤설정할 수 있습니다.

시작하기 전에

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

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

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

권한 및 역할

이 섹션에서는 대화형 SQL 변환기를 사용하는 데 필요한 Identity and Access Management(IAM) 권한과 그러한 권한을 부여하는 사전 정의된 IAM 역할에 대해 설명합니다. 이 섹션에서는 추가 변환 구성을 구성하는 데 필요한 권한도 설명합니다.

대화형 SQL 변환기 사용 권한

대화형 변환기를 사용하는 데 필요한 권한을 얻으려면 관리자에게 parent 리소스에 대한 MigrationWorkflow 편집자 (roles/bigquerymigration.editor) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 대화형 변환기를 사용하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

대화형 변환기를 사용하려면 다음 권한이 필요합니다.

bigquerymigration.workflows.create
bigquerymigration.workflows.get

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

추가 변환 구성을 구성할 수 있는 권한

변환 설정의 변환 구성 ID 및 변환 구성 소스 위치 필드를 사용하여 추가 변환 구성을 구성할 수 있습니다. 이러한 번역 구성을 구성하려면 다음 권한이 필요합니다.

bigquerymigration.workflows.get
bigquerymigration.workflows.list

다음과 같은 사전 정의된 IAM 역할은 추가 변환 구성을 구성하는 데 필요한 권한을 제공합니다.

roles/bigquerymigration.viewer

BigQuery IAM에 대한 자세한 내용은 IAM으로 액세스 제어를 참조하세요.

지원되는 SQL 언어

BigQuery 대화형 SQL 변환기는 다음 SQL 언어를 GoogleSQL로 변환할 수 있습니다.

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
Greenplum SQL
IBM DB2 SQL
MySQL SQL
Oracle SQL, PL/SQL, Exadata
PostgreSQL SQL
Trino 또는 PrestoSQL
Snowflake SQL
SQL Server T-SQL
SQLite
Vertica SQL

도우미 UDF로 지원되지 않는 SQL 함수 처리

소스 언어에서 BigQuery로 SQL을 변환할 때 일부 함수에는 직접적인 대응 항목이 없을 수 있습니다. 이 문제를 해결하기 위해 BigQuery 이전 서비스 (및 더 큰 BigQuery 커뮤니티)에서는 이러한 지원되지 않는 소스 방언 함수의 동작을 복제하는 도우미 사용자 정의 함수 (UDF)를 제공합니다.

이러한 UDF는 bqutil 공개 데이터 세트에 있는 경우가 많으므로 번역된 쿼리는 처음에 bqutil.<dataset>.<function>() 형식을 사용하여 이를 참조할 수 있습니다. 예를 들면 bqutil.fn.cw_count()입니다.

프로덕션 환경의 중요 고려사항:

bqutil는 초기 변환 및 테스트를 위해 이러한 도우미 UDF에 편리하게 액세스할 수 있도록 제공하지만 프로덕션 워크로드에 bqutil를 직접 사용하는 것은 다음과 같은 몇 가지 이유로 권장되지 않습니다.

버전 관리: bqutil 프로젝트는 이러한 UDF의 최신 버전을 호스팅하므로 시간이 지남에 따라 정의가 변경될 수 있습니다. bqutil를 직접 사용하면 UDF 로직이 업데이트될 경우 프로덕션 쿼리에서 예기치 않은 동작이나 중단 변경사항이 발생할 수 있습니다.
종속 항목 격리: 자체 프로젝트에 UDF를 배포하면 프로덕션 환경이 외부 변경사항으로부터 격리됩니다.
맞춤설정: 특정 비즈니스 로직이나 성능 요구사항에 더 적합하도록 이러한 UDF를 수정하거나 최적화해야 할 수 있습니다. 이는 내 프로젝트 내에 있는 경우에만 가능합니다.
보안 및 거버넌스: 조직의 보안 정책에 따라 프로덕션 데이터 처리를 위해 bqutil와 같은 공개 데이터 세트에 대한 직접 액세스가 제한될 수 있습니다. UDF를 제어된 환경에 복사하는 것은 이러한 정책에 부합합니다.

프로젝트에 도우미 UDF 배포

안정적인 프로덕션 사용을 위해 이러한 도우미 UDF를 자체 프로젝트 및 데이터 세트에 배포해야 합니다. 이렇게 하면 버전, 맞춤설정, 액세스를 완전히 제어할 수 있습니다. 이러한 UDF를 배포하는 방법에 관한 자세한 안내는 GitHub의 UDF 배포 가이드를 참고하세요. 이 가이드에서는 UDF를 환경에 복사하는 데 필요한 스크립트와 단계를 제공합니다.

위치

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

	리전 설명	리전 이름	세부정보
아시아 태평양
	델리	`asia-south2`
	홍콩	`asia-east2`
	자카르타	`asia-southeast2`
	멜버른	`australia-southeast2`
	뭄바이	`asia-south1`
	오사카	`asia-northeast2`
	서울	`asia-northeast3`
	싱가포르	`asia-southeast1`
	시드니	`australia-southeast1`
	타이완	`asia-east1`
	도쿄	`asia-northeast1`
유럽
	벨기에	`europe-west1`	낮은 CO₂
	베를린	`europe-west10`	낮은 CO₂
	EU 멀티 리전	`eu`
	핀란드	`europe-north1`	낮은 CO₂
	프랑크푸르트	`europe-west3`	낮은 CO₂
	런던	`europe-west2`	낮은 CO₂
	마드리드	`europe-southwest1`	낮은 CO₂
	밀라노	`europe-west8`
	네덜란드	`europe-west4`	낮은 CO₂
	파리	`europe-west9`	낮은 CO₂
	스톡홀름	`europe-north2`	낮은 CO₂
	토리노	`europe-west12`
	바르샤바	`europe-central2`
	취리히	`europe-west6`	낮은 CO₂
미주
	오하이오 주 콜럼부스	`us-east5`
	댈러스	`us-south1`	낮은 CO₂
	아이오와	`us-central1`	낮은 CO₂
	라스베이거스	`us-west4`
	로스앤젤레스	`us-west2`
	멕시코	`northamerica-south1`
	북버지니아	`us-east4`
	오리건	`us-west1`	낮은 CO₂
	퀘벡	`northamerica-northeast1`	낮은 CO₂
	상파울루	`southamerica-east1`	낮은 CO₂
	솔트레이크시티	`us-west3`
	산티아고	`southamerica-west1`	낮은 CO₂
	사우스캐롤라이나	`us-east1`
	토론토	`northamerica-northeast2`	낮은 CO₂
	미국 멀티 리전	`us`
아프리카
	요하네스버그	`africa-south1`
MiddleEast
	담맘	`me-central2`
	도하	`me-central1`
	이스라엘	`me-west1`

기본적으로 변환 규칙 기능은 다음 처리 위치에서 사용할 수 있습니다.

us미국(멀티 리전)
euEU(멀티 리전)
us-central1(아이오와)
europe-west4(네덜란드)

Gemini 기반 변환 구성은 특정 처리 위치에서만 사용할 수 있습니다. 자세한 내용은 Google 모델 엔드포인트 위치를 참고하세요.

쿼리를 GoogleSQL로 변환

쿼리를 GoogleSQL로 변환하려면 다음 단계를 따르세요.

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

BigQuery로 이동
편집기 창에서 더보기를 클릭한 다음 변환 설정을 선택합니다.
소스 언어에서 변환할 SQL 언어를 선택합니다.
선택사항. 처리 위치에서 변환 작업을 실행할 위치를 선택합니다. 예를 들어 유럽에 있고 데이터가 위치 경계를 넘어가지 않도록 하려면 eu 리전을 선택합니다.
저장을 클릭합니다.
편집기 창에서 더보기를 클릭한 다음 SQL 변환 사용 설정을 선택합니다.

편집기 창이 2개의 창으로 분할됩니다.
왼쪽 창에 변환할 쿼리를 입력합니다.
번역을 클릭합니다.

BigQuery에서 쿼리를 GoogleSQL로 변환하고 오른쪽 창에 표시합니다. 예를 들어 다음 스크린샷은 변환된 Teradata SQL을 보여줍니다.
선택사항: 변환된 GoogleSQL 쿼리를 실행하려면 실행을 클릭합니다.
선택사항: SQL 편집기로 돌아가려면 더보기를 클릭한 다음 SQL 변환 사용 중지를 선택합니다.

편집기 창이 단일 창으로 돌아갑니다.

대화형 SQL 변환기에서 Gemini 사용

대화형 SQL 변환기를 구성하여 대화형 SQL 변환기가 소스 SQL을 변환하는 방법을 조정할 수 있습니다. 이렇게 하려면 YAML 구성 파일에서 Gemini와 함께 사용할 자체 규칙을 제공하거나 SQL 객체 메타데이터 또는 객체 매핑 정보가 포함된 구성 YAML 파일을 제공하면 됩니다.

Gemini로 향상된 변환 규칙 만들기 및 적용하기

변환 규칙을 만들어 대화형 SQL 변환기가 SQL을 변환하는 방식을 맞춤설정할 수 있습니다. 대화형 SQL 변환기는 사용자가 할당하는 Gemini로 향상된 SQL 변환 규칙을 기준으로 변환을 조정하여 마이그레이션 요구에 따라 변환 결과를 맞춤설정할 수 있습니다. 이 기능은 특정 위치에서만 지원됩니다.

Gemini로 향상된 SQL 변환 규칙을 만들려면 콘솔에서 만들거나 구성 YAML 파일을 만들어 Cloud Storage에 업로드하면 됩니다.

콘솔

입력 SQL에 대해 Gemini로 향상된 SQL 변환 규칙을 만들려면 쿼리 편집기에 입력 SQL 쿼리를 작성한 다음 지원 > 맞춤설정을 클릭합니다. (미리보기)

번역 입력 맞춤설정

마찬가지로 출력 SQL의 Gemini로 향상된 SQL 변환 규칙을 만들려면 대화형 변환을 실행한 다음 지원 > 이 변환 맞춤설정을 클릭합니다.

번역 출력 맞춤설정

맞춤설정 메뉴가 표시되면 다음 단계를 계속 진행합니다.

다음 프롬프트 중 하나 또는 모두를 사용하여 변환 규칙을 만듭니다.
- 패턴 찾기 및 바꾸기 프롬프트에서 바꾸기 필드에 바꾸려는 SQL 패턴을 지정하고 대상 필드에는 이를 대체할 SQL 패턴을 입력합니다.
  
  SQL 패턴은 SQL 스크립트에 문, 절 또는 함수를 원하는 만큼 포함할 수 있습니다. 이 프롬프트를 사용하여 규칙을 만들면 Gemini로 향상된 SQL 변환이 SQL 쿼리에서 해당 SQL 패턴의 인스턴스를 식별하고 다른 SQL 패턴으로 동적으로 바꿉니다. 예를 들어 이 프롬프트를 사용하여 months_between (X,Y)와 일치하는 모든 항목을 date_diff(X,Y,MONTH)로 바꾸는 규칙을 만들 수 있습니다.
- 출력 변경사항을 설명하세요 필드에 SQL 변환 출력의 변경사항을 자연어로 입력합니다.
  
  이 프롬프트를 사용하여 규칙을 만들면 Gemini로 향상된 SQL 변환에서 요청을 식별하고 지정된 변경사항을 SQL 쿼리에 적용합니다.
미리보기를 클릭합니다.
Gemini에서 생성한 추천 대화상자에서 규칙에 따라 Gemini로 향상된 SQL 변환을 통해 SQL 쿼리에 적용된 변경사항을 검토합니다.
선택사항: 이후 변환에 사용할 이 규칙을 추가하려면 이 프롬프트 저장... 체크박스를 선택합니다.

규칙은 기본 구성 YAML 파일 또는 __default.ai_config.yaml에 저장됩니다. 이 구성 YAML 파일은 변환 설정의 변환 구성 소스 위치 필드에 지정된 대로 Cloud Storage 폴더에 저장됩니다. 번역 구성 소스 위치가 아직 설정되지 않은 경우 폴더 브라우저가 표시되어 선택할 수 있습니다. 구성 YAML 파일에는 구성 파일 크기 제한이 적용됩니다.
추천된 변경사항을 SQL 쿼리에 적용하려면 적용을 클릭합니다.

YAML

Gemini로 향상된 SQL 변환 규칙을 만들려면 Gemini 기반 구성 YAML 파일을 만들고 Cloud Storage에 업로드하면 됩니다. 자세한 내용은 Gemini 기반 구성 YAML 파일 만들기를 참고하세요.

Gemini로 향상된 SQL 변환 규칙을 만들어 Cloud Storage에 업로드한 후 다음을 실행하여 규칙을 적용할 수 있습니다.

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

BigQuery로 이동
쿼리 편집기에서 더보기 > 변환 설정을 클릭합니다.
변환 구성 소스 위치 필드에서 Cloud Storage 폴더에 저장된 Gemini 기반 YAML 파일의 경로를 지정합니다.
저장을 클릭합니다.

저장한 후 대화형 변환을 실행합니다. 대화형 변환기는 구성 YAML 파일의 규칙(사용 가능한 경우)을 기반으로 변환 변경사항을 제안합니다.

규칙에 따라 입력에 Gemini 추천을 사용할 수 있는 경우 추천 변경사항 미리보기 대화상자가 표시되고 변환 입력에 적용할 수 있는 변경사항이 표시됩니다. (미리보기)

규칙에 따라 출력에 Gemini 추천을 사용할 수 있는 경우 코드 편집기에 알림 배너가 표시됩니다. 추천을 검토하고 적용하려면 다음 단계를 따르세요.

코드 편집기의 양쪽에 있는 지원 > 추천 보기를 클릭하여 해당 쿼리에 대한 추천 변경사항을 다시 살펴봅니다.
Gemini에서 생성한 추천 대화상자에서 변환 규칙에 따라 Gemini가 SQL 쿼리에 적용한 변경사항을 검토합니다.
추천된 변경사항을 번역 출력에 적용하려면 적용을 클릭합니다.

Gemini 기반 구성 YAML 파일 업데이트

기존 구성 YAML 파일을 업데이트하려면 다음 단계를 따르세요.

Gemini에서 생성된 추천 대화상자에서 Gemini 규칙 구성 파일 보기를 클릭합니다.
구성 편집기가 표시되면 수정하려는 구성 YAML 파일을 선택합니다.
변경한 후 저장을 클릭합니다.
완료를 클릭하여 YAML 편집기를 닫습니다.
대화형 변환을 실행하여 업데이트된 규칙을 적용합니다.

번역 설명

대화형 변환을 실행한 후 Gemini에서 생성한 텍스트 설명을 요청할 수 있습니다. 생성된 텍스트에는 번역된 SQL 쿼리의 요약이 포함됩니다. 또한 Gemini는 소스 SQL 쿼리와 변환된 GoogleSQL 쿼리 간의 변환 차이와 불일치를 식별합니다.

Gemini에서 생성한 SQL 변환 설명을 보려면 다음 단계를 따르세요.

Gemini에서 생성한 SQL 변환 설명을 만들려면 지원을 클릭한 다음 이 변환 설명을 클릭합니다.

일괄 변환 구성 ID를 사용한 변환

일괄 변환 구성 ID를 제공하여 일괄 변환 작업과 동일한 변환 구성으로 대화형 쿼리를 실행할 수 있습니다.

쿼리 편집기에서 더보기 > 변환 설정을 클릭합니다.
변환 구성 ID 필드에 일괄 변환 구성 ID를 입력하여 완료된 BigQuery 일괄 이전 작업의 동일한 변환 구성을 적용합니다.

작업의 일괄 변환 구성 ID를 찾으려면 SQL 변환 페이지에서 일괄 변환 작업을 선택한 다음 변환 구성 탭을 클릭합니다. 일괄 변환 구성 ID가 리소스 이름으로 나열됩니다.
저장을 클릭합니다.

추가 구성으로 변환

Cloud Storage 폴더에 저장된 구성 YAML 파일을 지정하여 추가 변환 구성으로 대화형 쿼리를 실행할 수 있습니다. 변환 구성에는 변환 품질을 향상시킬 수 있는 소스 데이터베이스의 SQL 객체 메타데이터 또는 객체 매핑 정보가 포함될 수 있습니다. 예를 들어 대화형 SQL 변환 품질을 개선하기 위해 소스 데이터베이스의 DDL 정보 또는 스키마를 포함합니다.

변환 구성 소스 파일에 위치를 제공하여 변환 구성을 지정하려면 다음을 수행하세요.

쿼리 편집기에서 더보기 > 변환 설정을 클릭합니다.
변환 구성 소스 위치 필드에서 Cloud Storage 폴더에 저장된 변환 구성 파일의 경로를 지정합니다.

BigQuery 대화형 SQL 변환기는 변환 메타데이터 및 객체 이름 매핑이 포함된 메타데이터 ZIP 파일을 지원합니다. Cloud Storage에 파일을 업로드하는 방법에 대한 자세한 내용은 파일 시스템에서 객체 업로드를 참고하세요.
저장을 클릭합니다.

dwh-migration-dumper 도구에서 생성된 메타데이터 파일의 정보를 BigQuery 백엔드에 저장하려면 다음 단계를 따르세요.

쿼리 편집기에서 더보기 > 변환 설정을 클릭합니다.
메타데이터 캐싱 사용 설정 체크박스를 클릭합니다. 메타데이터 파일이 큰 작업의 경우 이 프로세스를 통해 후속 요청의 변환 지연 시간이 크게 줄어듭니다. 캐시된 메타데이터는 최대 7일 동안 활성 상태입니다. 이 기능은 미리보기 상태입니다. 이 기능에 대한 지원을 요청하거나 의견을 제공하려면 bq-edw-migration-support@google.com으로 문의하세요.
저장을 클릭합니다.

구성 파일 크기 제한사항

BigQuery 대화형 SQL 변환기에서 변환 구성 파일을 사용하는 경우 압축된 메타데이터 파일 또는 YAML 구성 파일의 크기가 50MB 미만이어야 합니다. 파일 크기가 50MB를 초과하면 대화형 변환기는 변환 중에 해당 구성 파일을 건너뛰고 다음과 유사한 오류 메시지를 생성합니다.

CONFIG ERROR: Skip reading file "gs://metadata-file.zip". File size (150,000,000 bytes) exceeds limit (50 MB).

메타데이터 파일 크기를 줄이는 한 가지 방법은 --database 또는 --schema 플래그를 사용해서 변환 입력 쿼리와 관련된 데이터베이스 또는 스키마의 메타데이터만 추출하는 것입니다. 메타데이터 파일을 생성할 때 이러한 플래그를 사용하는 방법은 전역 플래그를 참조하세요.

변환 오류 문제 해결

다음은 대화형 SQL 변환기를 사용할 때 자주 발생하는 오류입니다.

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

가장 정확한 변환을 보장하기 위해 쿼리 자체 전에 쿼리에 사용된 모든 테이블의 데이터 정의 언어(DDL) 문을 입력할 수 있습니다. 예를 들어 Amazon Redshift 쿼리 select table1.field1, table2.field1 from table1, table2 where table1.id = table2.id;를 변환하려면 다음 SQL 문을 대화형 SQL 변환기에 입력합니다.

create table schema1.table1 (id int, field1 int, field2 varchar(16));
create table schema1.table2 (id int, field1 varchar(30), field2 date);

select table1.field1, table2.field1
from table1, table2
where table1.id = table2.id;

가격 책정

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

다음 단계

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