이 페이지의 일부 또는 전체 정보는 S3NS의 신뢰할 수 있는 클라우드에 적용되지 않을 수 있습니다.

변환 API를 사용한 SQL 쿼리 변환

이 문서에서는 BigQuery에서 변환 API를 사용하여 다른 SQL 언어로 작성된 스크립트를 GoogleSQL 쿼리로 변환하는 방법을 설명합니다. 변환 API를 사용하면 워크로드를 BigQuery로 마이그레이션하는 프로세스를 간소화할 수 있습니다.

시작하기 전에

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

필요한 모든 권한이 있는지 확인합니다.
BigQuery Migration API를 사용 설정합니다.
변환할 SQL 스크립트와 쿼리가 포함된 소스 파일을 수집합니다.
Cloud Storage에 소스 파일 업로드

필수 권한

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

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

필수 권한

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

bigquerymigration.workflows.create
bigquerymigration.workflows.get

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

BigQuery Migration API 사용 설정

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

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

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

Cloud Storage에 입력 파일 업로드

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

지원되는 태스크 유형

변환 API는 다음 SQL 언어를 GoogleSQL로 변환할 수 있습니다.

Amazon Redshift SQL - Redshift2BigQuery_Translation
Apache HiveQL 및 Beeline CLI - HiveQL2BigQuery_Translation
Apache Spark SQL - SparkSQL2BigQuery_Translation
Azure Synapse T-SQL - AzureSynapse2BigQuery_Translation
Greenplum SQL - Greenplum2BigQuery_Translation
IBM Db2 SQL - Db22BigQuery_Translation
IBM Netezza SQL 및 NZPLSQL - Netezza2BigQuery_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
SQLite - SQLite2BigQuery_Translation
SQL Server T-SQL - SQLServer2BigQuery_Translation
Teradata 및 Teradata Vantage - Teradata2BigQuery_Translation
Vertica SQL - Vertica2BigQuery_Translation

도우미 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를 환경에 복사하는 데 필요한 스크립트와 단계를 제공합니다.

위치

다음 처리 위치에서 변환 API를 사용할 수 있습니다.

	리전 설명	리전 이름	세부정보
아시아 태평양
	델리	`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`
중동
	Dammam	`me-central2`
	도하	`me-central1`
	이스라엘	`me-west1`

변환 작업 제출

변환 API를 사용하여 변환 작업을 제출하려면 projects.locations.workflows.create 메서드를 사용하고 MigrationWorkflow 리소스의 인스턴스를 지원되는 태스크 유형으로 제공합니다.

작업이 제출되면 쿼리를 실행하여 결과를 얻을 수 있습니다.

일괄 변환 만들기

다음 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\"
              }
            },
            \"target_types\": \"TARGET_TYPES\",
        }
      }
  }
  }" \
  -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입니다.
TARGET_TYPES(선택사항): 생성된 출력 유형입니다. 지정하지 않으면 SQL이 생성됩니다.
- sql(기본값): 변환된 SQL 쿼리 파일입니다.
- suggestion: AI 생성 추천입니다.
출력은 출력 디렉터리의 하위 폴더에 저장됩니다. 하위 폴더의 이름은 TARGET_TYPES의 값을 기반으로 지정됩니다.
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가 포함된 응답을 반환합니다.

일괄 변환 예시

Cloud Storage 디렉터리 gs://my_data_bucket/teradata/input/의 Teradata SQL 스크립트를 변환하고 결과를 Cloud Storage 디렉터리 gs://my_data_bucket/teradata/output/에 저장하려면 다음 쿼리를 사용하면 됩니다.

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
       }
    }
  }
}

이 호출은 생성된 워크플로 ID가 포함된 메시지를 "name" 필드에 반환합니다.

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

워크플로의 업데이트된 상태를 가져오려면 GET 쿼리를 실행합니다. 작업이 진행되면 Cloud Storage로 출력을 전송합니다. 요청된 모든 target_types가 생성되면 작업 state가 COMPLETED로 변경됩니다. 태스크가 성공하면 gs://my_data_bucket/teradata/output에서 변환된 SQL 쿼리를 찾을 수 있습니다.

AI 추천을 사용한 일괄 변환 예시

다음 예시에서는 gs://my_data_bucket/teradata/input/ Cloud Storage 디렉터리에 있는 Teradata SQL 스크립트를 변환하고 추가 AI 추천과 함께 결과를 Cloud Storage 디렉터리 gs://my_data_bucket/teradata/output/에 저장합니다.

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
          "target_types": "suggestion",
       }
    }
  }
}

태스크가 성공적으로 실행되면 gs://my_data_bucket/teradata/output/suggestion Cloud Storage 디렉터리에서 AI 추천을 확인할 수 있습니다.

문자열 리터럴 입력 및 출력으로 대화형 변환 작업 만들기

다음 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: 작업이 처리되는 위치입니다.

위 명령어는 projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID 형식으로 작성된 워크플로 ID가 포함된 응답을 반환합니다.

작업이 완료되면 작업을 쿼리하고 워크플로가 완료된 후 응답에서 인라인 translation_literals 필드를 검사하여 결과를 확인할 수 있습니다.

대화형 변환 예시

Hive SQL 문자열 select 1을 대화형으로 변환하려면 다음 쿼리를 사용하면 됩니다.

"tasks": {
  string: {
    "type": "HiveQL2BigQuery_Translation",
    "translation_details": {
      "source_target_mapping": {
        "source_spec": {
          "literal": {
            "relative_path": "input_file",
            "literal_string": "select 1"
          }
        }
      },
      "target_return_literals": "sql/input_file",
    }
  }
}

리터럴에 원하는 relative_path를 사용할 수 있지만 target_return_literals에 sql/$relative_path를 포함하는 경우에만 변환된 리터럴이 결과에 표시됩니다. 단일 쿼리에 여러 리터럴을 포함할 수도 있습니다. 이 경우 각 상대 경로가 target_return_literals에 포함되어야 합니다.

이 호출은 생성된 워크플로 ID가 포함된 메시지를 "name" 필드에 반환합니다.

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

워크플로의 업데이트된 상태를 가져오려면 GET 쿼리를 실행합니다. "state"가 COMPLETED로 변경되면 작업이 완료된 것입니다. 태스크가 성공하면 응답 메시지에 변환된 SQL이 표시됩니다.

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "string": {
      "id": "0fedba98-7654-3210-1234-56789abcdef",
      "type": "HiveQL2BigQuery_Translation",
      /* ... */
      "taskResult": {
        "translationTaskResult": {
          "translatedLiterals": [
            {
              "relativePath": "sql/input_file",
              "literalString": "-- Translation time: 2023-10-05T21:50:49.885839Z\n-- Translation job ID: projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00\n-- Source: input_file\n-- Translated from: Hive\n-- Translated to: BigQuery\n\nSELECT\n    1\n;\n"
            }
          ],
          "reportLogMessages": [
            ...
          ]
        }
      },
      /* ... */
    }
  },
  "state": "COMPLETED",
  "createTime": "2023-10-05T21:50:49.543221Z",
  "lastUpdateTime": "2023-10-05T21:50:50.462758Z"
}

변환 출력 살펴보기

변환 작업을 실행한 후 다음 명령어를 사용하여 변환 작업 워크플로 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입니다.

응답에는 마이그레이션 워크플로의 상태와 target_return_literals에 있는 완료된 파일이 포함됩니다.

응답에는 마이그레이션 워크플로 상태와 target_return_literals에 있는 완료된 파일이 포함됩니다. 이 엔드포인트를 폴링하여 워크플로 상태를 확인할 수 있습니다.