Data Mapping Guide¶

개요¶

데이터 매핑은 YAML 파일의 mappings: 구조로 작성하고 CLI의 mapping_rule 파라미터로 적용합니다. mappings=는 현재 CLI 파라미터가 아닙니다.

mapping_rule=FILE_OR_GLOB[,FILE_OR_GLOB...]

각 glob pattern은 최소 하나의 일반 파일과 일치해야 합니다.

웹 콘솔의 매핑에서도 YAML 또는 표로 편집을 사용합니다. 표 편집은 Mapping ID·Source·Target·조회조건을 한 번 작성하는 공통 설정과 컬럼별 Source 컬럼·변환 SQL·Target 컬럼 대응표로 나뉩니다. 같은 Source라도 조회조건은 Mapping ID별로 독립적입니다.

작업 범위와 적재 방식

mapping_rule은 작업 범위를 직접 정의하므로 schemas, tables, query와 함께 사용할 수 없습니다.
Mapping은 이미 존재하며 metadata가 호환되는 Target에만 적재합니다.
table_action=APPEND|TRUNCATE만 지원합니다. REPLACE|STRUCTURE는 Target DDL 전에 거부됩니다.

1. 현재 YAML 형식¶

mappings:
  customer_mapping:
    source:
      owner: SRC_USER
      table_name: CUSTOMER
      condition: STATUS = 'ACTIVE'
    target:
      owner: TGT_USER
      table_name: CUSTOMER_COPY
    columns:
      - source_column: CUSTOMER_ID
        target_column: CUSTOMER_ID
      - conversion_rule: "UPPER(CUSTOMER_NAME)"
        target_column: CUSTOMER_NAME
      - conversion_rule: "FIRST_NAME || ' ' || LAST_NAME"
        target_column: FULL_NAME

Mapping ID¶

mappings: 아래 key는 mapping ID입니다. 여러 파일 전체에서 고유해야 하며 중복되면 DUPLICATE_MAPPING_ID 오류입니다. 같은 ID의 모든 정의를 거부하며 먼저 읽은 정의를 우선해서 사용하지 않습니다. 무관한 유효 mapping은 계속 검증할 수 있습니다.

Source와 Target routing¶

source.owner와 source.table_name은 읽을 Source를 지정합니다.
target.owner와 target.table_name은 적재할 실제 Target을 지정합니다.
source.condition은 WHERE 없이 사용하는 신뢰된 Oracle SQL 조건식입니다.
remap_schema, prefix, suffix, table_exclude는 mapping 대상에 적용되지 않습니다.

즉, mapping 작업의 routing은 YAML에 명시한 qualified Source/Target이 결정합니다. CLI의 source와 target은 접속 문자열이며 owner mapping을 대신하지 않습니다.

Column assignment¶

각 columns 항목에는 다음 규칙이 적용됩니다.

target_column을 지정합니다.
source_column 또는 conversion_rule 중 정확히 하나만 지정합니다.
Target column 중복은 허용되지 않습니다.
YAML key 중복도 허용되지 않습니다.
conversion_rule은 sandbox 표현식이 아니라 Source DB에서 실행되는 신뢰된 Oracle SQL입니다.
문자열 결합은 Oracle의 || 연산자를 사용합니다.

2. 파일 지정과 중복 규칙¶

mapping_rule=/secure/mapping/customer.yaml
mapping_rule="/secure/mapping/hr/*.yaml,/secure/mapping/sales/*.yaml"

목록은 쉼표로 한 번에 지정합니다. 같은 CLI 파라미터를 반복하면 기본 CLI 중복 규칙에 따라 오류가 발생합니다.

datatrans \
  source=SRC_USER/password@host:1521/SRCDB \
  target=TGT_USER/password@host:1521/TGTDB \
  mapping_rule="/secure/mapping/*.yaml" \
  table_action=APPEND \
  jobname=CUSTOMER_MAPPING

3. Parsing과 preflight¶

아래는 CLI 도움말과 현재 사전 검증 동작을 기준으로 정리한 parsing·preflight 안내입니다. 설치본의 MAPPING_PREFLIGHT_GUIDE.md에서 안내하는 주요 결과도 함께 설명합니다.

Mapping Rule Parsing¶

파일 접근, UTF-8, YAML 구조와 key를 검사합니다.

읽기 또는 YAML parsing에 실패한 파일은 제외하고 다른 파일을 계속 검사합니다.
Parsing 가능한 파일에서는 잘못된 entry만 제외하고 정상 entry를 계속 검사합니다.
Pattern이 파일과 일치하지 않거나 정상 entry가 하나도 없으면 작업을 중단합니다.
중복 YAML key는 MAPPING_YAML, 잘못된 entry 구조는 MAPPING_SCHEMA로 보고됩니다.
중복 YAML key가 있는 파일은 파일 전체를 거부합니다. Target column 중복은 대소문자를 구분하지 않고 해당 entry를 거부합니다.

MAPPING PREFLIGHT¶

Source expression 결과와 실제 Target metadata를 비교합니다. Preflight는 모든 mapping을 계속 검증해 오류를 한 번에 표시하며, 실제 모든 row의 변환 성공까지 보장하지는 않습니다.

표현식 결과 개수, Target 컬럼 존재 여부, 자료형 그룹, NUMBER precision/scale, BYTE/CHAR 길이, 필수 미매핑 컬럼과 가상·identity 컬럼을 검사합니다. 검증 후 메타데이터가 바뀌면 해당 작업의 새 처리 시작을 차단합니다.

상태	동작
`PASSED`	Warning과 Error 없이 계속 실행합니다.
`PASSED WITH WARNINGS`	상세 Warning을 표시하고 계속 실행합니다.
`PARTIAL`	오류 mapping은 제외하고 검증된 mapping만 실행합니다.
`FAILED`	Worker를 시작하지 않습니다. `Workers started : 0`으로 표시됩니다.

정상 mapping이 남아 실행되고 파일·entry·metadata 검증 오류가 일부 있었다면 최종 작업 상태는 COMPLETED_WITH_ERRORS입니다. 실행 가능한 mapping이 하나도 없거나 전역 설정·연결·저장소 무결성 오류가 있으면 전체 작업을 실패 처리합니다.

4. Preflight 요약¶

항목	의미
`Mapping files`	읽은 mapping 파일 수
`Rejected files`	접근 또는 parsing 오류로 제외한 파일 수
`Mapping entries`	mapping ID 수
`Accepted entries`	YAML/schema 검증을 통과한 mapping ID 수
`Rejected entries`	YAML/schema 검증에서 제외한 mapping ID 수
`Source tables`	중복을 제거한 Source table 수
`Target tables`	중복을 제거한 Target table 수
`Column assignments`	전체 Target column assignment 수
`Direct assignments`	`source_column` assignment 수
`Conversion assignments`	`conversion_rule` assignment 수
`Validated mappings`	Metadata 검증을 통과한 mapping 수
`Duplicate targets`	같은 Target을 추가로 사용하는 mapping 수
`Warnings` / `Errors`	계속 가능한 확인 항목 / 실행 불가 오류 수

집계 관계는 다음과 같습니다.

Column assignments = Direct assignments + Conversion assignments
Duplicate targets = Mapping entries - Target tables
Validated mappings <= Mapping entries

5. 같은 Target을 쓰는 Mapping¶

APPEND에서 여러 mapping이 같은 Target을 사용하면 DUPLICATE_TARGET Warning입니다. Row 순서와 중복 제거는 보장하지 않으며 Target constraint 동작을 따릅니다.

TRUNCATE에서 같은 Target을 여러 mapping이 사용하면 DUPLICATE_TARGET Error이며 해당 Target의 mapping 그룹은 실행할 수 없습니다. 반복해서 데이터를 비우는 것을 막기 위한 제한이며 무관한 유효 Target은 계속 처리할 수 있습니다.

6. 오류 코드¶

코드	의미
`MAPPING_FILE_ACCESS`	파일 접근 또는 UTF-8 오류
`MAPPING_YAML`	YAML syntax 또는 duplicate key 오류
`MAPPING_SCHEMA`	Mapping entry 구조 또는 필드 오류
`DUPLICATE_MAPPING_ID`	여러 entry의 mapping ID 중복
`SOURCE_METADATA`	Source expression 또는 metadata 조회 실패
`TARGET_METADATA`	Target metadata 조회 실패
`OUTPUT_CARDINALITY`	Expression 수와 결과 column 수 불일치
`UNKNOWN_TARGET_COLUMN`	Target column이 존재하지 않음
`INCOMPATIBLE_DATATYPE`	Source와 Target datatype이 호환되지 않음
`NUMBER_PRECISION_SCALE`	Target NUMBER precision 또는 scale 초과
`CHARACTER_LENGTH`	Target BYTE 또는 CHAR 길이 초과
`REQUIRED_TARGET_COLUMN`	필수 Target column이 mapping되지 않음
`VIRTUAL_COLUMN`	Virtual Target column에 직접 mapping
`IDENTITY_COLUMN`	Identity Target column에 직접 mapping
`METADATA_CHANGED`	Preflight 이후 metadata 변경
`DUPLICATE_TARGET`	TRUNCATE에서 여러 mapping이 같은 Target 사용
`MAPPING_METADATA`	기타 Mapping metadata 검증 오류

7. 안전 체크리스트¶

mapping_rule만 사용하고 mappings=를 사용하지 않았습니다.
schemas, tables, query를 함께 지정하지 않았습니다.
Source와 Target owner/table을 YAML에 명시했습니다.
APPEND|TRUNCATE와 기존 compatible Target만 사용했습니다.
Mapping ID, YAML key와 Target column이 중복되지 않습니다.
각 assignment에 source_column|conversion_rule 중 하나만 있습니다.
conversion_rule과 source.condition은 관리자가 검토한 신뢰된 Oracle SQL입니다.
PARTIAL이면 제외된 mapping과 최종 COMPLETED_WITH_ERRORS를 확인합니다.