일괄 변환을 위해 SQL 객체 이름 매핑

미리보기

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

참고: JSON을 사용한 객체 이름 매핑은 기존 일괄 처리 API에서만 지원됩니다. BigQuery Migration API를 사용하거나 Google Cloud 콘솔에서 일괄 작업을 시작하는 경우 대신 YAML 기반 객체 이름 매핑을 사용하세요.

이 문서는 일괄 변환 중에 SQL 객체 이름을 변경하도록 이름 매핑을 구성하는 방법을 설명합니다.

개요

이름 매핑을 사용하면 소스 파일에서 SQL 객체의 이름을 식별하고 BigQuery에서 이러한 객체의 대상 이름을 지정할 수 있습니다. 다음 구성요소 중 일부 또는 전부를 사용하여 객체의 이름 매핑을 구성할 수 있습니다.

• 이름 매핑 규칙은 다음으로 구성됩니다.
  • 소스 시스템에서 객체의 정규화된 이름을 제공하는 소스 이름 부분입니다.
  • 소스 객체의 유형을 식별하는 유형입니다.
  • BigQuery에서 객체의 이름을 제공하는 대상 이름 부분입니다.
• 지정하지 않은 소스 객체에 사용할 기본 데이터베이스 이름입니다.
• 지정하지 않은 모든 소스 객체에 사용할 기본 스키마 이름입니다.

이름 부분

다음 이름 부분의 조합을 사용하여 이름 매핑 규칙에 소스 및 대상 객체 이름의 값을 제공합니다.

• 데이터베이스: 이름 지정 계층 구조의 최상위 수준입니다. 소스 플랫폼에서는 프로젝트와 같은 대체 용어를 사용할 수 있습니다.
• 스키마: 이름 지정 계층 구조의 두 번째 수준입니다. 소스 플랫폼에서는 데이터 세트와 같은 대체 용어를 사용할 수 있습니다.
• 관계: 이름 지정 계층 구조의 세 번째 수준입니다. 소스 플랫폼에서는 테이블과 같은 대체 용어를 사용할 수 있습니다.
• 속성: 이름 지정 계층 구조의 최하위 수준입니다. 소스 플랫폼에서는 열과 같은 대체 용어를 사용할 수 있습니다.

객체 유형

또한 이름 매핑 규칙에서 이름을 변경할 소스 객체의 유형을 지정해야 합니다. 지원되는 객체 유형은 다음과 같습니다.

• Database: 객체 계층 구조의 최상위 객체입니다(예: database.schema.relation.attribute). 소스 플랫폼에서는 프로젝트와 같은 대체 용어를 사용할 수 있습니다. 객체 유형으로 database를 지정하면 DDL 문과 DML 문에서 소스 문자열에 대한 모든 참조가 변경됩니다.
• Schema: 객체 계층 구조의 두 번째 수준 객체입니다. 소스 플랫폼에서는 데이터 세트와 같은 대체 용어를 사용할 수 있습니다. 객체 유형으로 schema를 지정하면 DDL 문과 DML 문에서 소스 문자열에 대한 모든 참조가 변경됩니다.
• Relation: 객체 계층 구조의 세 번째 수준 객체입니다. 소스 플랫폼에서는 테이블과 같은 대체 용어를 사용할 수 있습니다. 객체 유형으로 relation을 지정하면 DDL 문의 소스 문자열에 대한 모든 참조가 변경됩니다.
• Relation alias: 세 번째 객체의 별칭입니다. 예를 들어 SELECT t.field1, t.field2 FROM myTable t; 쿼리에서 t는 관계 별칭입니다. 쿼리 SELECT field1, field2 FROM schema1.table1에서 table1은 관계 별칭이기도 합니다. 객체 유형으로 relation alias을 지정하면 DML 문의 소스 문자열에 대한 모든 참조에 대한 별칭이 생성됩니다. 예를 들어 tableA이 대상 이름으로 지정되면 앞의 예시는 각각 SELECT tableA.field1, tableA.field2 FROM myTable AS tableA;와 SELECT tableA.field1, tableA.field2 FROM schema1.table1 AS tableA로 변환됩니다.
• Function: 프로시져입니다(예: create procedure db.test.function1(a int)). 객체 유형으로 function을 지정하면 DDL 문과 DML 문에서 소스 문자열에 대한 모든 참조가 변경됩니다.
• Attribute: 객체 계층 구조의 네 번째 수준 객체입니다. 소스 플랫폼에서는 열과 같은 대체 용어를 사용할 수 있습니다. 객체 유형으로 attribute를 지정하면 DDL 문의 소스 문자열에 대한 모든 참조가 변경됩니다.
• Attribute alias: 4단계 객체의 별칭입니다. 예를 들어 SELECT field1 FROM myTable; 쿼리에서 field1은 속성 별칭입니다. 객체 유형으로 attribute alias를 지정하면 DML 문의 소스 문자열에 대한 모든 참조가 변경됩니다.

객체 유형의 필수 이름 부분

이름 매핑 규칙에서 객체를 설명하려면 다음 표의 각 객체 유형에 식별된 이름 부분을 사용합니다.

유형	소스 객체 이름				대상 객체 이름
	데이터베이스 이름 부분	스키마 이름 부분	관계 이름 부분	속성 이름 부분	데이터베이스 이름 부분	스키마 이름 부분	관계 이름 부분	속성 이름 부분
Database	X				X
Schema	X	X			X	X
Relation	X	X	X		X	X	X
Function	X	X	X		X	X	X
Attribute	X	X	X	X				X
Attribute alias	X	X	X	X				X
Relation alias			X				X

기본 데이터베이스

변환된 모든 객체에 BigQuery 프로젝트 이름을 추가하려면 변환 작업을 만들 때 기본 데이터베이스 이름을 지정하는 것이 가장 쉽습니다. 3단계 이름 지정이 사용되거나 4단계 이름 지정이 사용되지만 최상위 수준 객체 이름이 지정되지 않은 소스 파일에서 작동합니다.

예를 들어 기본 데이터베이스 이름 myproject를 지정하면 SELECT * FROM database.table과 같은 소스 문이 SELECT * FROM myproject.database.table로 변환됩니다. SELECT * FROM database.schema.table과 같이 이미 데이터베이스 이름 부분을 사용하는 객체가 있는 경우 이름 매핑 규칙을 사용하여 database.schema.table의 이름을 myproject.schema.table로 변경해야 합니다.

기본 스키마

4단계 이름 지정을 사용하지 않는 소스 파일에서 모든 객체 이름을 정규화하려면 변환 작업을 만들 때 기본 데이터베이스 이름 및 기본 스키마 이름을 모두 제공하면 됩니다. 기본 스키마 이름은 스키마 검색 경로 옵션에서 첫 번째 스키마 이름으로 제공됩니다.

예를 들어 기본 데이터베이스 이름 myproject와 기본 스키마 이름 myschema를 지정하면 다음 소스 문은

• SELECT * FROM database.table
• SELECT * FROM table1

아래와 같이 변환됩니다.

• SELECT * FROM myproject.database.table.
• SELECT * FROM myproject.myschema.table1

이름 매핑 규칙 동작

다음 섹션에서는 이름 매핑 규칙의 동작을 설명합니다.

규칙 상속이 객체 계층 구조를 따라 이동

상위 수준 객체에 영향을 주는 이름 변경은 대상 객체, 그리고 동일한 계층 구조에 있는 모든 하위 객체에 영향을 미칩니다.

객체 유형이 schema인 다음 이름 매핑 규칙을 지정하는 경우를 예로 들 수 있습니다.

이름 부분	소스	대상
데이터베이스	sales_db	sales
스키마	cust_mgmt	cms
관계
속성

적용되면 sales_db.cust_mgmt 스키마 아래에서 모든 relation 및 attribute 객체의 데이터베이스 및 스키마 이름 부분도 변경됩니다. 예를 들어 sales_db.cust_mgmt.history라는 relation 객체는 sales.cms.history가 됩니다.

반대로 하위 수준의 객체를 대상으로 하는 이름 변경은 객체 계층 구조에서 상위 또는 동일 수준의 객체에 영향을 주지 않습니다.

객체 유형이 relation인 다음 이름 매핑 규칙을 지정하는 경우를 예로 들 수 있습니다.

이름 부분	소스	대상
데이터베이스	sales_db	sales
스키마	cust_mgmt	cms
관계	clients	accounts
속성

적용하면 객체 계층 구조의 sales_db 또는 sales_db.cust_mgmt 수준에서 다른 객체의 이름이 변경되지 않습니다.

가장 구체적인 규칙이 적용됨

하나의 이름 매핑 규칙만 객체에 적용됩니다. 여러 규칙이 단일 객체에 영향을 줄 수 있는 경우 가장 낮은 수준의 이름 부분에 영향을 미치는 규칙이 적용됩니다. 예를 들어 database 유형 이름 매핑 규칙과 schema 유형 이름 매핑 규칙 모두 relation 객체의 이름에 영향을 줄 수 있는 경우 schema 유형 이름 매핑 규칙이 적용됩니다.

유형과 소스 값의 고유한 조합 사용

유형 및 소스 값이 동일한 이름 매핑 규칙을 두 개 이상 지정할 수 없습니다. 예를 들어 다음과 같은 이름 매핑 규칙을 모두 지정할 수는 없습니다.

	규칙 1, attribute 유형		규칙 2, attribute 유형
이름 부분	소스	대상	소스	대상
데이터베이스	project		project
스키마	dataset1		dataset1
관계	table1		table1
속성	lname	last_name	lname	lastname

일치하는 attribute 및 attribute alias 이름 매핑 규칙 만들기

attribute 유형 이름 매핑 규칙을 사용하여 DDL 문의 속성 이름을 변경할 때는 attribute alias 이름 매핑 규칙을 만들어 DML 문에서 해당 속성의 이름을 변경해야 합니다.

이름 변경사항이 하위로 전파되지 않음

이름 변경 사항은 이름 규칙으로 전파되지 않습니다. 예를 들어 database1 이름을 project1로 변경하는 이름 매핑 규칙을 만들고 project1을 project2로 만드는 또 다른 이름 매핑 규칙을 만든 경우 변환기는 database1을 project2로 매핑하지 않습니다.

4단계 이름이 없는 소스 객체 처리

Teradata와 같은 일부 소스 시스템은 세 가지 이름 부분을 사용하여 객체 이름을 정규화합니다. 대부분의 소스 시스템에서는 SQL 언어에서 정규화된 이름을 사용할 수도 있습니다. 예를 들어 database1.schema1.table1, schema1.table1, table1을 사용하면 서로 다른 컨텍스트에서 동일한 객체를 참조할 수 있습니다. 소스 파일에 4단계 객체 이름을 사용하지 않는 객체가 포함된 경우 기본 데이터베이스 이름 및 기본 스키마 이름을 사용하여 원하는 이름 매핑을 얻을 수 있습니다.

기본 데이터베이스 이름 또는 기본 스키마 이름으로 이름 매핑 규칙을 사용하는 예시는 이름 완료 수준이 다양한 객체의 데이터베이스 이름 부분 변경 및 부분적으로 정규화된 관계 객체 이름 변경을 참조하세요.

이름 매핑 예시

이 섹션의 예시를 사용하여 일반적인 사용 사례에서 이름 매핑 규칙이 작동하는 방식을 확인하세요.

정규화된 객체의 데이터베이스 이름 부분 변경

다음 예시에서는 정규화된 이름을 갖는 모든 database, schema, relation, function 객체의 데이터베이스 이름 부분을 td_project에서 bq_project로 변경합니다.

소스 및 대상 이름 부분

이름 부분	소스	대상
데이터베이스	td_project	bq_project
스키마
관계
속성

유형

• database

예시 입력

• SELECT * FROM td_project.schema.table;
• SELECT * FROM td_project.schema1.table1;

결과 예시

• SELECT * FROM bq_project.schema.table;
• SELECT * FROM bq_project.schema1.table1

이름 완료 수준이 다양한 객체의 데이터베이스 이름 부분 변경

다음 예시에서는 모든 객체 유형에 대해 데이터베이스 이름 부분을 project에서 bq_project로 바꾸고, 지정하지 않은 객체의 데이터베이스 이름 부분으로 bq_project도 추가합니다.

이렇게 하려면 변환 작업을 구성할 때 이름 매핑 규칙 외에 기본 데이터베이스 값도 지정해야 합니다. 기본 데이터베이스 이름을 지정하는 방법에 대한 자세한 내용은 변환 작업 제출을 참조하세요.

기본 데이터베이스 값

• project

소스 및 대상 이름 부분

이름 부분	소스	대상
데이터베이스	project	bq_project
스키마
관계
속성

유형

• database

예시 입력

• SELECT * FROM project.schema.table;
• SELECT * FROM schema1.table1;

결과 예시

• SELECT * FROM bq_project.schema.table;
• SELECT * FROM bq_project.schema1.table1

정규화된 객체의 데이터베이스 이름 부분 및 스키마 이름 부분 변경

다음 예시에서는 데이터베이스 이름 부분 warehouse1을 myproject로 변경하고 database1 스키마 이름 부분도 mydataset로 변경합니다.

또한 relation 유형을 사용하고 관계 이름 부분의 소스 및 목표 값을 지정하여 동일한 방식으로 relation 객체 이름의 일부를 변경할 수 있습니다.

소스 및 대상 이름 부분

이름 부분	소스	대상
데이터베이스	warehouse1	myproject
스키마	database1	mydataset
관계
속성

유형

• schema

예시 입력

• SELECT * FROM warehouse1.database1.table1;
• SELECT * FROM database2.table2;

결과 예시

• SELECT * FROM myproject.mydataset.table1;
• SELECT * FROM __DEFAULT_DATABASE__.database2.table2;

완전히 정규화된 relation 객체 이름 변경

다음 예시에서는 mydb.myschema.mytable 이름을 mydb.myschema.table1로 바꿉니다.

소스 및 대상 이름 부분

이름 부분	소스	대상
데이터베이스	mydb	mydb
스키마	myschema	myschema
관계	mytable	table1
속성

유형

• relation

예시 입력

• CREATE table mydb.myschema.mytable(id int, name varchar(64));

결과 예시

• CREATE table mydb.myschema.table1(id integer, name string(64));

부분적으로 정규화된 relation 객체 이름 변경

다음 예시에서는 myschema.mytable 이름을 mydb.myschema.table1로 바꿉니다.

기본 데이터베이스 값

• mydb

소스 및 대상 이름 부분

이름 부분	소스	대상
데이터베이스	mydb	mydb
스키마	myschema	myschema
관계	mytable	table1
속성

유형

• relation

예시 입력

• CREATE table myschema.mytable(id int, name varchar(64));

결과 예시

• CREATE table mydb.myschema.table1(id integer, name string(64));

relation alias 객체 이름 변경

다음 예시에서는 relation alias 객체 table의 모든 인스턴스 이름을 t로 바꿉니다.

소스 및 대상 이름 부분

이름 부분	소스	대상
데이터베이스
스키마
관계	table	t
속성

유형

• relation alias

예시 입력

• SELECT table.id, table.name FROM mydb.myschema.mytable table

결과 예시

• SELECT t.id, t.name FROM mydb.myschema.mytable AS t

function 객체 이름 변경

다음 예시에서는 mydb.myschema.myfunction 이름을 mydb.myschema.function1로 바꿉니다.

소스 및 대상 이름 부분

이름 부분	소스	대상
데이터베이스	mydb	mydb
스키마	myschema	myschema
관계	myprocedure	procedure1
속성

유형

• function

예시 입력

• CREATE PROCEDURE mydb.myschema.myprocedure(a int) BEGIN declare i int; SET i = a + 1; END;
• CALL mydb.myschema.myprocedure(7)

결과 예시

• CREATE PROCEDURE mydb.myschema.procedure1(a int) BEGIN declare i int; SET i = a + 1; END;
• CALL mydb.myschema.procedure1(7);

attribute 객체 이름 변경

다음 예시에서는 mydb.myschema.mytable.myfield 이름을 mydb.myschema.mytable.field1로 바꿉니다. attribute 객체는 객체 계층 구조의 최하위 수준에 있으므로 이 이름 매핑은 다른 객체의 이름을 변경하지 않습니다.

소스 및 대상 이름 부분

이름 부분	소스	대상
데이터베이스	mydb
스키마	myschema
관계	mytable
속성	myfield	field1

유형

• attribute

예시 입력

• CREATE table mydb.myschema.mytable(myfield int, name varchar(64), revenue int);

결과 예시

• CREATE table mydb.myschema.mytable(field1 int, name varchar(64), revenue int);

attribute alias 객체 이름 변경

다음 예시에서는 mydb.myschema.mytable.myfield 이름을 mydb.myschema.mytable.field1로 바꿉니다. attribute alias 객체는 객체 계층 구조의 최하위 수준에 있으므로 이 이름 매핑은 다른 객체의 이름을 변경하지 않습니다.

소스 및 대상 이름 부분

이름 부분	소스	대상
데이터베이스	mydb
스키마	myschema
관계	mytable
속성	myfield	field1

유형

• attribute alias

예시 입력

• SELECT myfield, name FROM mydb.myschema.mytable;

결과 예시

• SELECT field1, name FROM mydb.myschema.mytable;

JSON 파일 형식

Google Cloud 콘솔이 아닌 JSON 파일을 사용하여 이름 매핑 규칙을 지정하는 경우 JSON 파일이 다음 형식을 따라야 합니다.

{
  "name_map": [
    {
      "source": {
        "type": "string",
        "database": "string",
        "schema": "string",
        "relation": "string",
        "attribute": "string"
      },
      "target": {
        "database": "string",
        "schema": "string",
        "relation": "string",
        "attribute": "string"
      }
    }
  ]
}

파일 크기는 5MB 미만이어야 합니다.

변환 작업의 이름 매핑 규칙 지정에 대한 자세한 내용은 변환 작업 제출을 참조하세요.

JSON 예시

다음 예시에서는 JSON 파일을 사용하여 이름 매핑 규칙을 지정하는 방법을 보여줍니다.

예시 1

이 예시의 이름 매핑 규칙은 다음과 같이 객체 이름을 변경합니다.

• project.dataset2.table2 relation 객체의 인스턴스 이름을 bq_project.bq_dataset2.bq_table2로 바꿉니다.
• project database 객체의 모든 인스턴스 이름을 bq_project로 바꿉니다. 예를 들어 project.mydataset.table2은 bq_project.mydataset.table2가 되고 CREATE DATASET project.mydataset는 CREATE DATASET bq_project.mydataset가 됩니다.

{
  "name_map": [{
    "source": {
      "type": "RELATION",
      "database": "project",
      "schema": "dataset2",
      "relation": "table2"
    },
    "target": {
      "database": "bq_project",
      "schema": "bq_dataset2",
      "relation": "bq_table2"
    }
  }, {
    "source": {
      "type": "DATABASE",
      "database": "project"
    },
    "target": {
      "database": "bq_project"
    }
  }]
}

예 2

이 예시의 이름 매핑 규칙은 다음과 같이 객체 이름을 변경합니다.

• DDL 및 DML 문에서 project.dataset2.table2.field1 attribute 객체의 인스턴스 이름을 bq_project.bq_dataset2.bq_table2.bq_field로 바꿉니다.

{
  "name_map": [{
    "source": {
      "type": "ATTRIBUTE",
      "database": "project",
      "schema": "dataset2",
      "relation": "table2",
      "attribute": "field1"
    },
    "target": {
      "database": "bq_project",
      "schema": "bq_dataset2",
      "relation": "bq_table2",
      "attribute": "bq_field"
    }
  }, {
    "source": {
      "type": "ATTRIBUTE_ALIAS",
      "database": "project",
      "schema": "dataset2",
      "relation": "table2",
      "attribute": "field1"
    },
    "target": {
      "database": "bq_project",
      "schema": "bq_dataset2",
      "relation": "bq_table2",
      "attribute": "bq_field"
    }
  }]
}