Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

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

이 문서에서는 BigQuery의 일괄 SQL 변환기를 사용하여 다른 SQL 언어로 작성된 스크립트를 GoogleSQL 쿼리로 변환하는 방법을 설명합니다. Google Cloud 콘솔 또는 명령줄에서 번역 작업을 제출하고 결과를 검토할 수 있습니다.

이 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

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

소스 파일 수집

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

메타데이터 파일 만들기

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

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

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

구성 YAML 파일 만들기

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

구성 YAML 파일을 사용하려면 소스 파일이 포함된 Cloud Storage 버킷에 업로드하세요.

Cloud Storage에 입력 파일 업로드

변환할 쿼리와 스크립트가 포함된 소스 파일을 Cloud Storage에 업로드합니다. 소스 파일이 포함된 동일한 Cloud Storage 버킷 및 디렉터리에 메타데이터 파일 또는 구성 YAML 파일을 업로드할 수도 있습니다. 버킷 생성 및 Cloud Storage에 파일 업로드에 대한 자세한 내용은 버킷 만들기 및 파일 시스템에서 객체 업로드를 참조하세요.

변환 작업 제출 방법 선택

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

Google Cloud 콘솔: 사용자 인터페이스를 사용하여 작업을 구성하고 제출합니다.
명령줄 도구: 변환 구성 파일에서 작업을 설명하고 Google Cloud CLI 또는 bq 명령줄 도구 명령줄 도구를 사용하여 제출합니다.

두 옵션 모두 소스 파일을 Cloud Storage에 업로드해야 하며 동일한 종류의 번역 작업을 만듭니다. 명령줄에서 제출한 작업은Google Cloud 콘솔의 변환 작업 목록에 계속 표시됩니다.

변환 작업 제출

다음 옵션 중 하나를 사용하여 변환 작업을 시작하고 진행 상황을 확인합니다. 나중에 결과를 검토하려면 번역 출력 살펴보기를 참고하세요.

콘솔

이 단계에서는 소스 파일을 Cloud Storage 버킷에 업로드했다고 가정합니다.

Google Cloud 콘솔을 사용하여 일괄 번역 작업을 제출하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 SQL 변환 페이지로 이동합니다.

SQL 변환으로 이동
SQL 변환 패널에서 변환 시작을 클릭합니다.
변환 구성에 다음을 입력합니다.
1. 표시 이름에 변환 작업 이름을 입력합니다. 이름에는 문자, 숫자 또는 밑줄을 사용할 수 있습니다.
2. 처리 위치에서 변환 작업을 실행할 위치를 선택합니다. 예를 들어 개발자가 유럽에 있고 데이터가 위치 경계를 넘어가지 않게 하려면 eu 리전을 선택합니다. 변환 작업은 소스 파일 버킷과 동일한 위치를 선택할 때 최고의 성능을 발휘합니다.
3. 소스 언어에서 변환할 SQL 언어를 선택합니다.
4. 대상 언어에서 GoogleSQL을 선택합니다.
다음을 클릭합니다.
파일 위치 세부정보에서 번역 입력 및 출력에 사용할 Cloud Storage 경로를 지정합니다. 경로를 bucket_name/folder_name/ 형식으로 입력하거나 찾아보기 옵션을 사용하여 폴더로 이동할 수 있습니다.
1. 출력 디렉터리 위치에서 변환된 파일의 대상 Cloud Storage 폴더 경로를 지정합니다. 이는 모든 번역 출력의 루트 디렉터리 역할을 합니다.
2. 변환할 SQL 파일의 경로가 포함된 입력 디렉터리 위치를 하나 이상 선택합니다.
3. 필요한 경우 각 입력 디렉터리에 루트 출력 디렉터리 아래에 있는 출력 하위 디렉터리 이름을 지정할 수 있습니다.
다음을 클릭합니다.
메타데이터와 추가 번역 출력을 맞춤설정하는 데 필요한 선택적 설정을 선택합니다.
선택사항: 변환 동작을 추가로 맞춤설정하려면 구성 YAML 파일을 만들고 이러한 파일을 입력 Cloud Storage 버킷에 배치합니다. 이러한 파일을 사용하여 객체 이름을 바꾸고, 최적화를 사용 설정하고, Gemini로 번역을 개선하는 등의 작업을 할 수 있습니다. 구성 YAML 파일에 대한 자세한 내용은 구성 YAML 파일 만들기를 참고하세요.
만들기를 클릭하여 변환 작업을 시작합니다.

변환 작업을 만든 후 변환 작업 목록에서 상태를 확인할 수 있습니다.

bq

gcloud CLI 또는 bq 명령줄 도구 명령줄 도구를 사용하여 일괄 번역 작업을 제출하려면 다음 단계를 따르세요.

이 단계에서는 소스 파일을 Cloud Storage 버킷에 업로드했다고 가정합니다.

번역 구성 파일 만들기

변환 구성 파일은 소스 파일의 경로, 출력 대상, 변환의 소스 및 타겟 언어를 정의합니다. 이 파일은 YAML 또는 JSON으로 작성할 수 있습니다.

다음 예는 Teradata에서 BigQuery로의 변환을 위한 변환 구성 YAML 파일을 보여줍니다.

tasks:
  translation_task:
    type: Teradata2BigQuery_Translation
    translationDetails:
      sourceTargetMapping:
      - sourceSpec:
          baseUri: gs://bq-translations/input
        targetSpec:
          relativePath: output
      targetBaseUri: gs://bq-translations
      targetTypes:
      - sql
      sourceEnvironment:
        defaultDatabase: default_db
        schemaSearchPath:
        - foo

다음 예는 Teradata에서 BigQuery로의 변환을 위한 변환 구성 JSON 파일을 보여줍니다.

{
  "tasks": {
    "translation_task": {
      "type": "Teradata2BigQuery_Translation",
      "translationDetails": {
        "sourceTargetMapping": [
          {
            "sourceSpec": {
              "literal": {
                "literalString": "sel 1",
                "relativePath": "my_input_1"
              },
              "encoding": "UTF-8"
            }
          },
          {
            "sourceSpec": {
              "literal": {
                "literalString": "sel 2",
                "relativePath": "my_input_2"
              },
              "encoding": "UTF-8"
            }
          }
        ],
        "targetReturnLiterals": [
          "sql/my_input_1",
          "sql/my_input_2"
        ]
      }
    }
  }
}

Google Cloud CLI로 작업 제출

번역 작업을 만들고 워크플로를 실행하려면 다음 명령어를 사용하세요.

gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE

워크플로를 만들고 실행한 후 워크플로 링크와 함께 즉시 반환하려면 --async 플래그를 추가합니다.

gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE --async

번역 작업을 나열하려면 다음 명령어를 사용하세요.

gcloud bq migration-workflows list --location=LOCATION

특정 변환 작업의 세부정보를 보려면 다음 명령어를 사용하세요.

gcloud bq migration-workflows describe projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

다음을 바꿉니다.

LOCATION: 이 변환 작업을 실행하는 Google Cloud 프로젝트의 위치입니다.
CONFIG_FILE: 번역 구성 파일의 경로입니다.
PROJECT_ID: 이 변환 작업을 실행하는 Google Cloud 프로젝트의 ID입니다.
WORKFLOW_ID: 번역 작업의 ID입니다.

bq 명령줄 도구로 작업 제출

번역 작업을 실행하려면 다음 명령어를 사용합니다.

bq mk --migration_workflow --location=LOCATION --config_file=CONFIG_FILE

모든 번역 작업을 나열하려면 다음 명령어를 사용하세요.

bq ls --migration_workflow --location=LOCATION

특정 번역 작업에 대한 세부정보를 보려면 다음 명령어를 사용하세요.

bq show --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

목록에서 번역 작업을 삭제하려면 다음 명령어를 사용합니다.

bq rm --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

다음을 바꿉니다.

LOCATION: 이 변환 작업을 실행하는 Google Cloud 프로젝트의 위치입니다.
CONFIG_FILE: 번역 구성 파일의 경로입니다.
PROJECT_ID: 이 변환 작업을 실행하는 Google Cloud 프로젝트의 ID입니다.
WORKFLOW_ID: 번역 작업의 ID입니다.

출력 파일 검색

변환 작업은 변환 구성 파일의 targetBaseUri 필드에 설정한 Cloud Storage 디렉터리에 결과를 씁니다. 이 타겟 디렉터리에는 번역된 파일, 번역 요약 보고서, AI 추천 파일이 포함됩니다.

출력을 로컬 머신에 복사하려면 다음 명령어를 사용하세요.

gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY

다음을 바꿉니다.

TARGET_URI: 대상 기본 URI(예: gs://my_data_bucket/teradata/output/)
LOCAL_DIRECTORY: 파일을 수신하는 로컬 디렉터리입니다.

명령줄에서 제출한 작업도Google Cloud 콘솔의 변환 작업 목록에 표시됩니다. 번역 출력의 품질을 검토하려면 번역 출력 살펴보기를 참고하세요.

변환 출력 살펴보기

명령줄에서 작업을 제출했는지 Google Cloud 콘솔에서 제출했는지와 관계없이 Google Cloud 콘솔에서 변환 작업 결과를 검토할 수 있습니다. 일괄 SQL 변환기는 다음 파일을 지정된 대상으로 출력합니다.

변환된 파일
CSV 형식의 변환 요약 보고서
AI 추천 파일입니다.

Google Cloud 콘솔 출력

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

Google Cloud 콘솔에서 SQL 변환 페이지로 이동합니다.

SQL 변환으로 이동
변환 작업 목록에서 변환 세부정보를 보려는 작업을 찾습니다. 그런 다음 변환 작업 이름을 클릭합니다. 작업의 전반적인 품질, 코드 입력 줄 수(공백 줄 및 주석 제외), 변환 프로세스 중에 발생한 문제 목록을 보여주는 흐름 차트 시각화를 확인할 수 있습니다. 왼쪽에서 오른쪽으로 수정하는 것이 좋습니다. 초기 단계의 문제는 후속 단계에서 추가 문제를 일으킬 수 있습니다.
포인터를 오류 또는 경고 막대 위로 가져가 제안을 검토하여 번역 작업을 디버그하는 다음 단계를 결정합니다.
로그 요약 탭을 선택하여 문제 카테고리, 제안된 작업, 각 문제의 발생 빈도 등 변환 문제의 요약을 확인합니다. 흐름 차트 시각화 막대를 클릭하여 문제를 필터링할 수 있습니다. 또한 문제 카테고리를 선택하여 해당 문제 카테고리와 연결된 로그 메시지를 볼 수 있습니다.
로그 메시지 탭을 선택하여 문제 카테고리, 특정 문제 메시지, 문제가 발생한 파일에 대한 링크 등 각 번역 문제에 관한 세부정보를 확인하세요. Sankey 시각화 막대를 클릭하여 문제를 필터링할 수 있습니다. 로그 메시지 탭에서 문제를 선택하여 적용 가능한 경우 입력 및 출력 파일을 표시하는 코드 탭을 열 수 있습니다.
작업 세부정보 탭을 클릭하여 변환 작업 구성 세부정보를 확인합니다.

요약 보고서

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

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

Google Cloud 콘솔에서 SQL 변환 페이지로 이동합니다.

SQL 변환으로 이동
변환 작업 목록에서 원하는 작업을 찾은 후 작업 이름을 클릭하거나 옵션 더보기 > 세부정보 표시를 클릭합니다.
작업 세부정보 탭의 변환 보고서 섹션에서 translation_report.csv를 클릭합니다.
객체 세부정보 페이지에서 인증된 URL 행의 값을 클릭하여 브라우저에서 파일을 확인합니다.

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

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

코드 탭

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

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

Google Cloud 콘솔에서 SQL 변환 페이지로 이동합니다.

SQL 변환으로 이동
변환 작업 목록에서 원하는 작업을 찾은 후 작업 이름을 클릭하거나 옵션 더보기 > 세부정보 표시를 클릭합니다.
코드 탭을 선택합니다. 코드 탭은 다음 패널로 구성됩니다.
- 파일 탐색기: 변환에 사용되는 모든 SQL 파일이 포함되어 있습니다. 파일을 클릭하여 번역 입력 및 출력과 번역의 번역 문제를 확인합니다.
- Gemini로 향상된 입력: 변환 엔진에서 변환한 입력 SQL입니다. Gemini 구성에서 소스 SQL에 대한 Gemini 맞춤설정 규칙을 지정한 경우 변환기는 먼저 원본 입력을 변환한 다음 Gemini로 향상된 입력을 변환합니다. 원본 입력을 보려면 원본 입력 보기를 클릭합니다.
- 변환 출력: 변환 결과입니다. Gemini 구성에서 타겟 SQL에 대한 Gemini 맞춤설정 규칙을 지정한 경우 변환이 변환된 결과에 Gemini로 향상된 출력으로 적용됩니다. Gemini로 향상된 출력을 사용할 수 있는 경우 Gemini 추천 버튼을 클릭하여 Gemini로 향상된 출력을 검토할 수 있습니다.
(선택사항) BigQuery 대화형 SQL 변환기에서 입력 파일과 출력 파일을 보려면 수정을 클릭합니다. 파일을 수정하고 출력 파일을 Cloud Storage에 다시 저장할 수 있습니다.

구성 탭

구성 탭에서 구성 YAML 파일을 추가, 이름 변경, 보기 또는 수정할 수 있습니다. 스키마 탐색기에는 지원되는 구성 유형의 문서가 표시되므로 구성 YAML 파일을 작성하는 데 도움이 됩니다. 구성 YAML 파일을 수정한 후 작업을 다시 실행하여 새 구성을 사용할 수 있습니다.

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

Google Cloud 콘솔에서 SQL 변환 페이지로 이동합니다.

SQL 변환으로 이동
변환 작업 목록에서 원하는 작업을 찾은 후 작업 이름을 클릭하거나 옵션 더보기 > 세부정보 표시를 클릭합니다.
변환 세부정보 창에서 구성 탭을 클릭합니다.

SQL 변환 페이지에서 구성 탭을 확인합니다.

새 구성 파일을 추가하려면 다음 단계를 따르세요.

more_vert 옵션 더보기 > 구성 YAML 파일 만들기를 클릭합니다.
새 구성 YAML 파일의 유형, 위치, 이름을 선택할 수 있는 패널이 표시됩니다.
만들기를 클릭합니다.

기존 구성 파일을 수정하려면 다음 단계를 따르세요.

구성 YAML 파일을 클릭합니다.
파일을 수정한 다음 저장을 클릭합니다.
다시 실행을 클릭하여 수정된 구성 YAML 파일을 사용하는 새 변환 작업을 실행합니다.

more_vert 옵션 더보기 > 이름 바꾸기를 클릭하여 기존 구성 파일의 이름을 바꿀 수 있습니다.

변환된 파일

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

도우미 UDF를 사용하여 지원되지 않는 SQL 함수 처리

소스 언어의 SQL을 BigQuery로 변환할 때 일부 함수에는 직접적으로 상응하는 함수가 없을 수 있습니다. 이 문제를 해결하기 위해 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를 배포하는 것이 좋습니다. 환경에 도우미 UDF를 배포하는 데 필요한 스크립트와 단계에 대한 자세한 내용은 UDF 배포를 참고하세요.

문제 해결

이 섹션에서는 개별 쿼리를 디버깅하는 방법과 가장 일반적인 번역 오류를 해결하는 방법을 설명합니다.

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

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

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

Google Cloud 콘솔에서 SQL 변환 페이지로 이동합니다.

SQL 변환으로 이동
변환 작업 목록에서 원하는 작업을 찾은 후 옵션 더보기 > 대화형 변환 열기를 클릭합니다.

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

대화형 SQL 변환기에서 일괄 변환 파일을 디버그하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 SQL 변환 페이지로 이동합니다.

SQL 변환으로 이동
변환 작업 목록에서 원하는 작업을 찾은 후 작업 이름을 클릭하거나 옵션 더보기 > 세부정보 표시를 클릭합니다.
번역 세부정보 창에서 코드 탭을 클릭합니다.
파일 탐색기에서 파일 이름을 클릭하여 파일을 엽니다.
출력 파일 이름 옆에 있는 수정을 클릭하여 대화형 SQL 변환기(프리뷰)에서 파일을 엽니다.

이제 해당 일괄 변환 구성 ID를 사용하는 대화형 SQL 변환기에 입력 파일과 출력 파일이 채워집니다.
수정된 출력 파일을 Cloud Storage에 다시 저장하려면 대화형 SQL 변환기에서 저장 > GCS에 저장을 클릭합니다.

변환 오류 문제 해결

다음 섹션에서는 일괄 SQL 변환기를 사용할 때 일반적으로 발생하는 오류를 설명합니다.

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

일괄 SQL 변환기를 사용하여 쿼리를 변환한 후 RelationNotFound 또는 AttributeNotFound 오류와 함께 변환이 실패할 수 있습니다.

Google Cloud 콘솔의 BigQuery에서 변환 세부정보 페이지로 이동하여 로그 메시지 탭을 열면 실패한 변환을 확인할 수 있습니다.

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

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

Gemini로 번역 문제 해결하기

RelationNotFound 또는 AttributeNotFound 오류로 인해 실패한 변환 작업을 수정하려면 Gemini를 사용하여 다음 문제를 해결할 수도 있습니다.

번역 세부정보 페이지로 이동하여 로그 메시지 탭을 엽니다.
카테고리 열에 RelationNotFound 또는 AttributeNotFound 메시지가 있는 쿼리를 클릭합니다.
코드 탭에서 오류가 포함된 파일과 줄로 이동하려면

오류 메시지
작업 열에서 추천 수정을 클릭합니다.
다음 옵션 중 하나를 선택합니다. 적용 또는 적용 후 다시 실행
- 생성된 스키마 파일을 출력 디렉터리에서 입력 디렉터리로 복사하려면 적용을 클릭합니다.
- 생성된 스키마 파일을 출력 디렉터리에서 입력 디렉터리로 복사하고 다시 실행 창을 열려면 적용 및 다시 실행을 클릭합니다.

할당량 및 한도

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

가격 책정

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

다음 단계

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

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

시작하기 전에

SQL 변환 사용 설정

필수 권한

필수 권한

소스 파일 수집

메타데이터 파일 만들기

구성 YAML 파일 만들기

Cloud Storage에 입력 파일 업로드

변환 작업 제출 방법 선택

변환 작업 제출

콘솔

bq

번역 구성 파일 만들기

Google Cloud CLI로 작업 제출

bq 명령줄 도구로 작업 제출

출력 파일 검색

변환 출력 살펴보기

Google Cloud 콘솔 출력

요약 보고서

코드 탭

구성 탭

변환된 파일

도우미 UDF를 사용하여 지원되지 않는 SQL 함수 처리

프로덕션 환경 고려사항

프로젝트에 도우미 UDF 배포

문제 해결

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

변환 오류 문제 해결

RelationNotFound 또는 AttributeNotFound 변환 문제

Gemini로 번역 문제 해결하기

할당량 및 한도

가격 책정

다음 단계

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