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

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

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

제한사항

대화형 SQL 변환기를 사용하려면 Google 계정으로 로그인해야 합니다. 대화형 SQL 변환기에서는 제휴 ID 사용을 지원하지 않습니다.

시작하기 전에

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

위치

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

	리전 설명	리전 이름	세부정보
아시아 태평양
	도쿄	`asia-northeast1`
	뭄바이	`asia-south1`
	싱가포르	`asia-southeast1`
	시드니	`australia-southeast1`
유럽
	EU 멀티 리전	`eu`
	바르샤바	`europe-central2`
	핀란드	`europe-north1`	낮은 CO₂
	마드리드	`europe-southwest1`	낮은 CO₂
	벨기에	`europe-west1`	낮은 CO₂
	런던	`europe-west2`	낮은 CO₂
	프랑크푸르트	`europe-west3`	낮은 CO₂
	네덜란드	`europe-west4`	낮은 CO₂
	취리히	`europe-west6`	낮은 CO₂
	파리	`europe-west9`	낮은 CO₂
	토리노	`europe-west12`
미주
	상파울루	`southamerica-east1`	낮은 CO₂
	미국 멀티 리전	`us`
	아이오와	`us-central1`	낮은 CO₂
	사우스캐롤라이나	`us-east1`
	북버지니아	`us-east4`
	오하이오 주 콜럼부스	`us-east5`
	댈러스	`us-south1`	낮은 CO₂
	오리건	`us-west1`	낮은 CO₂
	로스앤젤레스	`us-west2`
	솔트레이크시티	`us-west3`

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

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

쿼리를 GoogleSQL로 변환

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

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

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

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

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

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

대화형 SQL 변환기 구성

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

변환 규칙 만들기

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

Gemini로 향상된 SQL 변환 규칙을 만들려면 다음 중 하나를 수행합니다.

콘솔

Gemini로 향상된 SQL 변환 규칙을 만들려면 다음을 수행합니다.

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

규칙은 기본 구성 YAML 파일 또는 __default.ai_config.yaml에 저장됩니다. 이 구성 YAML 파일은 변환 설정의 변환 구성 소스 위치 필드에 지정된 대로 Cloud Storage 폴더에 저장됩니다. 구성 YAML 파일은 최대 10개의 변환 규칙을 지원할 수 있으며 구성 파일 크기 제한이 적용됩니다.
추천된 변경사항을 번역 출력에 적용하려면 적용을 클릭합니다.

YAML

구성 YAML 파일을 만들고 Cloud Storage에 업로드하여 Gemini로 향상된 SQL 변환 규칙을 만들 수 있습니다.

요구사항

변환 규칙 YAML 파일은 서픽스가 .ai_config.yaml이어야 합니다. 예를 들면 rules_1.ai_config.yaml입니다.

제한사항

대화형 SQL 변환기에는 변환 규칙 YAML 파일 하나만 적용할 수 있습니다.
각 변환 규칙 YAML 파일은 최대 10개의 규칙을 지원하며 구성 파일 크기 제한이 적용됩니다.

지원되는 필드

다음 예시에서는 자연어 프롬프트를 사용하여 Gemini로 향상된 변환 규칙 YAML 파일을 만드는 방법을 보여줍니다.

rewrite_target: TARGET
instruction: NL_PROMPT

다음을 바꿉니다.

TARGET: 변환 규칙을 입력 SQL(SOURCE_SQL)에 적용할지 아니면 출력 SQL(TARGET_SQL, 기본값)에 적용할지 지정합니다.
NL_PROMPT: 자연어로 대상 SQL의 변경사항을 설명합니다. Gemini로 향상된 SQL 변환이 요청을 식별하고 지정된 변경사항을 적용합니다.

여러 변환 규칙(최대 10개)으로 변환 규칙 YAML 파일을 만들 수도 있습니다. 각 규칙은 규칙을 설명하는 자연어 프롬프트(instruction)와 하나의 SQL 패턴(input)을 다른 패턴(output)으로 바꾸는 하나 이상의 예시로 구성될 수 있습니다. 변환 규칙은 instruction 필드, 하나 이상의 examples 필드를 사용하거나 두 유형의 필드를 모두 사용하여 규칙을 설명할 수 있습니다.

rewrite_target: TARGET
instruction: NL_PROMPT
translation_rules:
- instruction: NL_RULE_1
  examples:
  - input: RULE_1_INPUT_1
    output: RULE_1_OUTPUT_1
  - input: RULE_1_INPUT_2
    output: RULE_1_OUTPUT_2
- instruction: NL_RULE_2
  examples:
  - input: RULE_2_INPUT_1
    output: RULE_2_OUTPUT_1
…
…

다음을 바꿉니다.

NL_RULE_1(선택사항): 자연어로 변환 규칙을 설명합니다.
RULE_1_INPUT_1(선택사항): 바꾸려는 SQL 패턴입니다.
RULE_1_OUTPUT_1(선택사항): input을 바꾼 후 예상되는 SQL 패턴입니다.

필요에 따라 translation_rules(최대 10개) 및 examples를 더 추가할 수 있습니다.

Gemini로 향상된 SQL 변환 규칙 YAML 파일의 예시는 변환 규칙 YAML 파일 예시를 참조하세요.

다음 변환에 변환 규칙 YAML 파일 적용

변환 규칙 YAML 파일을 적용하려면 다음 안내를 따르세요.

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

변환 규칙 YAML 파일 예시

다음 샘플은 Gemini로 향상된 SQL 변환 규칙 YAML 파일의 예시입니다.

예시 1: 다른 함수로 바꿀 함수를 지정합니다.

translation_rules:
- instruction:  "Remove upper() function"
  examples:
  - input: "upper(X)"
    output: "X"

예시 2: 단일 YAML 파일에 여러 변환 규칙을 지정합니다.

translation_rules:
- instruction:  "Remove upper() function"
  examples:
  - input: "upper(X)"
    output: "X"
- instruction: "Insert a comment at the head that explains each statement in detail."

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

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

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

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

추가 구성으로 변환

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

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

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

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

구성 파일 크기 제한사항

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

다음 단계

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

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

제한사항

시작하기 전에

권한 및 역할

대화형 SQL 변환기 사용 권한

필수 권한

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

지원되는 SQL 언어

위치

쿼리를 GoogleSQL로 변환

대화형 SQL 변환기 구성

변환 규칙 만들기

콘솔

YAML

요구사항

제한사항

지원되는 필드

다음 변환에 변환 규칙 YAML 파일 적용

변환 규칙 YAML 파일 예시

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

추가 구성으로 변환

구성 파일 크기 제한사항

변환 오류 문제 해결

RelationNotFound 또는 AttributeNotFound 변환 문제

가격 책정

다음 단계

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