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

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

변환 규칙 기능을 사용하여 대화형 SQL 변환기가 SQL을 변환하는 방법을 맞춤설정할 수 있습니다.

이 SQL 변환기에서 지원하는 SQL 언어 목록은 지원되는 SQL 언어를 참조하세요.

지원되는 처리 위치 목록은 위치를 참조하세요.

시작하기 전에

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

SQL 변환 사용 설정

필수 API를 사용 설정하고 BigQuery SQL 변환기를 사용하는 데 필요한 권한을 가져옵니다. 자세한 내용은 SQL 변환 사용 설정을 참조하세요.

필수 권한

대화형 변환기, 변환 API 또는 일괄 SQL 변환기로 변환 작업을 만드는 데 필요한 권한을 얻으려면 관리자에게 parent 리소스에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

• 마이그레이션 작업 보기 및 모니터링: MigrationWorkflow 뷰어 (roles/bigquerymigration.viewer)
• 마이그레이션 작업 제출: MigrationWorkflow 편집자 (roles/bigquerymigration.editor)
• 입력 및 파일에 대해 Cloud Storage 버킷에 액세스: 스토리지 객체 관리자 (roles/storage.objectAdmin) - 소스 및 대상 Cloud Storage 버킷에 대한 권한

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 대화형 변환기, 변환 API 또는 일괄 SQL 변환기로 변환 작업을 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

대화형 변환기, 변환 API 또는 일괄 SQL 변환기로 변환 작업을 만들려면 다음 권한이 필요합니다.

• 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

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

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

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

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

프로덕션 환경 관련 중요 고려사항

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

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

프로젝트에 도우미 UDF 배포

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

위치

대화형 SQL 변환기는 일부 처리 위치에서만 사용할 수 있습니다. 자세한 내용은 위치를 참조하세요.

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

쿼리를 GoogleSQL로 변환

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

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

   BigQuery로 이동

2. 편집기 창에서 도구 > 변환 설정 을 클릭합니다.

3. 소스 언어에서 변환할 SQL 언어를 선택합니다.

4. (선택사항) 처리 위치에서 변환 작업을 실행할 위치를 선택합니다. 예를 들어 유럽에 있고 데이터가 위치 경계를 넘어가지 않도록 하려면 eu 리전을 선택합니다.

5. 저장 을 클릭합니다.

6. 편집기 창에서 도구 > SQL 변환 사용 설정을 클릭합니다.

   편집기 창이 2개의 창으로 분할됩니다.

7. 왼쪽 창에 변환할 쿼리를 입력합니다.

8. 번역 을 클릭합니다.

   BigQuery에서 쿼리를 GoogleSQL로 변환하고 오른쪽 창에 표시합니다. 예를 들어 다음 스크린샷은 변환된 Teradata SQL을 보여줍니다.

   

9. (선택사항) 변환된 GoogleSQL 쿼리를 실행하려면 실행 을 클릭합니다.

10. 선택사항: SQL 편집기로 돌아가려면 더보기 > SQL 변환 사용 중지를 클릭합니다.

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

대화형 SQL 변환기와 함께 Gemini 사용

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

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

참고: 프리뷰 기능에 대한 지원을 받고 의견을 제출하려면 [e-mail]으로 문의하세요.

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

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

콘솔

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

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

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

1. 다음 프롬프트 중 하나 또는 모두를 사용하여 변환 규칙을 만듭니다.

   • 패턴 찾기 및 바꾸기 프롬프트에서 바꾸기 필드에 바꾸려는 SQL 패턴을 지정하고 대상 필드에는 이를 대체할 SQL 패턴을 입력합니다.

     SQL 패턴은 SQL 스크립트에 문, 절 또는 함수를 원하는 만큼 포함할 수 있습니다. 이 프롬프트를 사용하여 규칙을 만들면 Gemini로 향상된 SQL 변환이 SQL 쿼리에서 해당 SQL 패턴의 인스턴스를 식별하고 다른 SQL 패턴으로 동적으로 바꿉니다. 예를 들어 이 프롬프트를 사용하여 months_between (X,Y)와 일치하는 모든 항목을 date_diff(X,Y,MONTH)로 바꾸는 규칙을 만들 수 있습니다.

   • 출력 변경사항을 설명하세요 필드에서 SQL 변환 출력의 변경사항을 자연어로 설명합니다.

     이 프롬프트를 사용하여 규칙을 만들면 Gemini로 향상된 SQL 변환에서 요청을 식별하고 지정된 변경사항을 SQL 쿼리에 적용합니다.

2. 미리보기를 클릭합니다.

3. Gemini에서 생성한 추천 대화상자에서 규칙에 따라 Gemini로 향상된 SQL 변환을 통해 SQL 쿼리에 적용된 변경사항을 검토합니다.

   

4. (선택사항) 이후 변환에 사용할 이 규칙을 추가하려면 이 프롬프트 저장... 체크박스를 선택합니다.

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

5. 추천된 변경사항을 SQL 쿼리에 적용하려면 적용 을 클릭합니다.

YAML

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

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

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

   BigQuery로 이동

2. 쿼리 편집기에서 도구 > 변환 설정을 클릭합니다.

3. 변환 구성 소스 위치 필드에서 Cloud Storage 폴더에 저장된 Gemini 기반 YAML 파일의 경로를 지정합니다.

4. 저장을 클릭합니다.

   저장되면 대화형 변환을 실행합니다. 대화형 변환기는 구성 YAML 파일에 규칙이 있는 경우 이를 기반으로 변환 변경사항을 제안합니다.

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

규칙에 따라 출력에 Gemini 추천이 제공되는 경우 코드 편집기에 알림 배너가 표시됩니다. 이러한 추천을 검토하고 적용하려면 다음을 수행하세요.

1. 코드 편집기의 양쪽에서 Assist > 추천 보기 를 클릭하여 해당 쿼리에 대한 추천 변경사항을 다시 확인합니다.

   

2. Gemini에서 생성한 추천 대화상자에서 변환 규칙에 따라 Gemini에서 SQL 쿼리에 적용한 변경사항을 검토합니다.

3. 추천된 변경사항을 변환 출력에 적용하려면 적용을 클릭합니다.

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

기존 구성 YAML 파일을 업데이트하려면 다음을 수행하세요.

1. Gemini에서 생성한 추천 대화상자에서 Gemini 규칙 구성 파일 보기 를 클릭합니다.

2. 구성 편집기가 표시되면 수정할 구성 YAML 파일을 선택합니다.

3. 변경사항을 적용하고 저장 을 클릭합니다.

4. 완료 를 클릭하여 YAML 편집기를 닫습니다.

5. 대화형 변환을 실행하여 업데이트된 규칙을 적용합니다.

변환 설명

미리보기

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '현재 상태 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

참고: Gemini로 향상된 SQL 변환을 사용하면 Gemini 모델로 스크립트에 대한 텍스트 설명을 생성할 수 있습니다. Gemini로 향상된 SQL 변환에서는 제한된 양의 Gemini를 무료로 사용할 수 있습니다. 이 사용량은 대부분의 마이그레이션 프로젝트에 충분합니다. 한도 상향을 요청하거나 이 프리뷰 기능에 대한 지원을 받고 의견을 제공하려면 다음 주소로 문의해 주세요. [e-mail].

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

Gemini에서 생성한 SQL 변환 설명을 가져오려면 다음을 수행하세요.

1. Gemini에서 생성한 SQL 변환 설명을 만들려면 Assist를 클릭한 후 이 변환 설명을 클릭합니다.

   

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

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

1. 쿼리 편집기에서 도구 > 변환 설정을 클릭합니다.

2. 변환 구성 ID 필드에서 완료된 BigQuery 일괄 마이그레이션 작업의 동일한 변환 구성을 적용할 일괄 변환 구성 ID를 제공합니다.

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

3. 저장을 클릭합니다.

추가 구성으로 변환

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

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

1. 쿼리 편집기에서 도구 > 변환 설정을 클릭합니다.

2. 변환 구성 소스 위치 필드에서 Cloud Storage 폴더에 저장된 변환 구성 파일의 경로를 지정합니다.

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

3. 저장을 클릭합니다.

구성 파일 크기 제한

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 변환 문제

대화형 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;

Gemini로 변환 문제 해결

미리보기

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '현재 상태 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

참고: 이 기능에 대한 의견을 제공하거나 지원을 요청하려면 [e-mail]으로 문의하세요.

RelationNotFound 또는 AttributeNotFound 오류로 실패한 변환 작업을 수정하려면 Gemini를 사용하여 다음 단계에 따라 이러한 문제를 해결해 볼 수도 있습니다.

1. 변환 세부정보 페이지로 이동하여 로그 메시지 탭을 엽니다.

2. 카테고리 열에 RelationNotFound 또는 AttributeNotFound 메시지가 있는 쿼리를 클릭합니다.

3. 추천 수정사항 을 클릭합니다.

4. 적용 을 클릭합니다.

5. 번역 을 클릭하여 쿼리를 다시 변환합니다.

가격 책정

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

다음 단계

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

• 마이그레이션 개요
• 마이그레이션 평가
• 스키마 및 데이터 전송 개요
• 일괄 SQL 변환
• 데이터 파이프라인
• 데이터 보안 및 거버넌스
• 데이터 검증 도구