파일 배치 동기화의 모드와 세부 설정
파일 기반 동기화를 만든 뒤에는 동기화 페이지의 Configurations 탭에서 설정을 바꿀 수 있습니다. 트랜잭션 유형과 파일 필터를 함께 선택하여 어떤 파일을 다시 가져올지, 이전 결과를 유지할지 결정합니다.
수집 모드 선택
| 원하는 결과 | 트랜잭션 유형 | 핵심 필터 | 출력 데이터셋 뷰 |
|---|---|---|---|
| 대상 파일 전체를 매번 다시 반영 | SNAPSHOT | 없음 | 이번 실행에서 수집한 전체 파일 |
| 새 파일을 계속 누적 | APPEND | Exclude files already synced | 지금까지 수집한 파일의 누적 집합 |
| 새 파일을 누적하고 변경된 파일 갱신 | UPDATE | Exclude files already synced와 수정 시각 또는 파일 크기 비교 | 지금까지 수집한 각 경로의 최신 파일 |
| 이번 실행에서 처음 수집한 파일만 유지 | SNAPSHOT | Exclude files already synced | 이번 실행의 새 파일만 남는 뷰 |
파일의 식별 기준은 경로 이름입니다. APPEND는 현재 뷰의 기존 파일을 수정할 수 없고, UPDATE는 기존 경로의 파일 내용을 덮어쓸 수 있습니다. 두 유형 모두 행 단위 갱신 명령을 뜻하지 않습니다.
전체 파일을 다시 반영: SNAPSHOT
기본 모드는 SNAPSHOT이며 필터를 지정하지 않습니다. 원천 시스템의 지정한 하위 폴더 아래에 있는 모든 파일을 매번 가져옵니다. 이전 실행에서 수집한 파일도 다시 포함하며, 결과 뷰는 이번 SNAPSHOT 트랜잭션의 파일 집합입니다.
전체 파일 집합을 반영하려는 목적과 다음 필터는 충돌할 수 있습니다.
| 필터 | 영향 |
|---|---|
| Exclude files already synced | 전체 파일 대신 이번 실행의 새 파일만 남기는 방식으로 바뀝니다. |
| Limit number of files | 제한이 전체 파일 수보다 작으면 어떤 파일이 포함될지 일정하지 않은 일부만 결과에 들어갑니다. |
| At least N files | 하위 폴더의 파일 수가 N보다 작으면 빈 트랜잭션이 생기고 수집 파일 수가 0이 됩니다. N 이상이면 이 조건은 결과를 바꾸지 않습니다. |
새 파일을 누적: APPEND
APPEND와 Exclude files already synced를 함께 사용합니다. 이전에 수집하지 않은 경로의 파일만 가져오며, 여러 실행의 APPEND 트랜잭션이 누적되어 결과 뷰를 구성합니다.
이때 Last modified date나 File size 비교를 켜면 기존 경로의 파일도 변경 후 다시 수집하려고 시도합니다. APPEND는 기존 파일을 덮어쓸 수 없으므로 이런 설정은 목적과 맞지 않습니다. 기존 파일의 변경을 반영해야 한다면 UPDATE를 사용합니다.
새 파일과 변경된 파일 반영: UPDATE
다음과 같이 구성합니다.
- 트랜잭션 유형을
UPDATE로 지정합니다. - Exclude files already synced를 사용합니다.
- 그 필터에서 Last modified date, File size 중 하나 이상을 비교하도록 설정합니다.
각 실행은 새 경로의 파일과 변경된 파일을 가져옵니다. 결과 뷰에는 지금까지 수집한 경로마다 최신 버전이 남습니다. 원천에서 파일이 사라져도 해당 경로는 결과 뷰에 남습니다.
이 모드는 원천 시스템이 기존 파일을 수정하는 동작을 바꿀 수 없을 때 사용합니다. 수집량은 새 파일과 변경 파일로 줄어들지만, 기존 파일을 덮어쓰면 후속 파이프라인의 추가 전용 입력 조건이 깨져 증분 처리를 유지할 수 없습니다.
UPDATE 트랜잭션이 기존 파일을 건드리지 않고 새 파일만 추가한 경우에는 증분성이 깨지지 않습니다. 문제는 UPDATE라는 이름 자체가 아니라 실제로 기존 파일을 덮어쓰는 변경입니다.
이번에 처음 수집한 파일만 유지: SNAPSHOT과 제외 필터
SNAPSHOT과 Exclude files already synced를 결합하면 이전에 수집한 파일을 제외하고 이번 실행의 새 파일만 담은 뷰를 만듭니다. 최근 실행 구간에 새로 나타난 파일만 후속 작업에 필요할 때 사용하는 방식입니다. 이전 실행에서 가져온 파일은 현재 결과 뷰에 보이지 않습니다.
여기에 Limit number of files를 추가하면 최근 구간의 파일 수가 제한을 넘을 때 일부 파일이 다음 실행으로 밀립니다. 처리되지 못한 파일이 계속 쌓이면 이후 실행에서 오래된 파일도 들어오므로 최근 파일만 유지하려는 목적이 깨질 수 있습니다. 제한에 걸린 파일 중 어떤 파일을 먼저 가져올지도 일정하지 않습니다.
모드와 함께 사용할 수 있는 범위 필터
하위 폴더, 경로 정규식과 필요한 파일 유형을 제한하는 필터는 수집 범위를 정하는 데 사용할 수 있습니다. Last modified after로 오래된 파일을 제외하거나 Path does not match로 .sh 같은 실행 파일을 제외하는 경우가 여기에 해당합니다.
수집 모드와 특히 강하게 연결되는 필터는 Exclude files already synced, At least N files, Limit number of files입니다. 이 세 필터를 바꿀 때는 파일 선택뿐 아니라 결과 뷰의 의미도 확인합니다.
실패 시 트랜잭션 처리
파일 배치 동기화는 트랜잭션 단위로 반영합니다. 어느 지점에서 실패하더라도 트랜잭션을 중단하고 그 실행에서 가져온 파일을 하나도 커밋하지 않습니다.
가령 파일 100만 개 중 마지막 파일 하나를 남기고 네트워크 오류가 발생하면, 앞서 업로드한 파일도 현재 데이터셋 뷰에 반영되지 않으므로 뷰는 변경되지 않습니다.
한 실행에서 처리하는 파일 수가 많을수록 일시적인 오류가 많은 재작업을 만들 수 있습니다. 새 파일만 추가되는 원천이라면 APPEND와 파일 수 제한을 사용하여 작은 배치씩 커밋하는 방법을 검토합니다.
기본 설정
| 항목 | 필수 여부 | 동작 |
|---|---|---|
| Subfolder | 필수 | 소스 안에서 수집할 파일 위치를 지정합니다. 하위의 모든 중첩 파일과 폴더가 대상에 포함됩니다. |
| Filters | 선택 | 수집 전에 대상 파일을 제한합니다. |
| Transformers | 선택 | Foundry에 업로드하기 전에 파일에 기본 변환을 적용합니다. |
| Completion strategies | 기존 설정 조회만 가능 | 성공적으로 수집한 뒤 원천 파일이나 빈 상위 폴더의 삭제를 시도합니다. 새 동기화에는 설정할 수 없습니다. |
파일 필터
| 필터 | 동작 |
|---|---|
| Exclude files already synced | 이미 수집한 파일을 제외합니다. 선택한 비교 기준에 따라 새 파일 또는 수정 시각이나 크기가 달라진 파일을 수집합니다. |
| Modified since last sync | 지난 동기화 이후 추가되거나 수정된 파일만 수집합니다. 현재 S3와 Google Cloud Storage에서 지원하는 더 가벼운 대안입니다. |
| Path matches | 커넥터 루트 기준의 상대 경로가 정규식에 맞는 파일만 수집합니다. |
| Path does not match | 커넥터 루트 기준의 상대 경로가 정규식에 맞지 않는 파일만 수집합니다. |
| Last modified after | 지정한 날짜와 시각 이후 수정된 파일만 수집합니다. |
| File size is between | 지정한 최소 및 최대 바이트 범위에 해당하는 파일만 수집합니다. |
| Any file has path matching | 정규식에 맞는 상대 경로의 파일이 하나라도 있으면, 다른 필터로 제외되지 않은 해당 하위 폴더의 파일을 모두 수집합니다. |
| At least N files | 필터링 후 남은 파일이 N개 이상일 때만 그 파일들을 수집합니다. |
| Limit number of files | 한 트랜잭션에서 가져올 파일 수를 제한합니다. 증분 동기화의 신뢰성을 높이는 데 사용할 수 있습니다. |
전체 목록 검사 비용
Exclude files already synced는 실행할 때마다 모든 파일을 검사하므로 파일 수가 많으면 확장성에 한계가 있습니다.
과거 데이터는 SNAPSHOT 동기화로 처리하고, 더 작은 최근 데이터 범위에는 이미 수집한 파일을 제외하는 증분 동기화를 별도로 구성하는 방법을 사용할 수 있습니다. 커넥터가 지원한다면 Modified since last sync도 검토합니다.
수정 시각을 사용하는 필터의 조건
Modified since last sync는 원천이 보고하는 마지막 수정 시각에 의존합니다. S3 호환 엔드포인트에서는 내용이 바뀔 때마다 수정 시각이 갱신되는지, 시계가 안정적이고 정확한지 제공자에게 확인해야 합니다. 이 조건을 충족하지 못하면 Exclude files already synced를 사용합니다.
수집 전 파일 변환
Transformers는 선택한 파일에 압축, 결합이나 복호화 같은 처리를 적용한 뒤 Foundry에 업로드합니다.
| 변환 | 동작과 제한 |
|---|---|
| Compress with Gzip | Gzip으로 압축 |
| Concatenate multiple files | 여러 파일을 하나로 결합 |
| Rename files | 파일 이름의 지정한 부분 문자열을 다른 문자열로 바꿈. 일치하는 모든 부분을 치환 |
| Decrypt with PGP | PGP로 암호화한 파일 복호화. 에이전트에 PGP 키가 구성되어 있어야 하며 Foundry 워커에서는 사용 불가 |
| Append timestamp to filenames | 각 수집 파일 이름에 사용자 지정 형식의 타임스탬프 추가 |
이름에서 디렉터리 경로를 제거하는 변환에는 ^(.*/)를 /로 바꾸는 설정을 사용할 수 있습니다.
가능하면 수집 전 변환보다 Foundry 안의 Pipeline Builder와 Code Repositories에서 처리하는 방식이 권장됩니다. 그렇게 하면 변환의 계보와 브랜치 관리를 활용할 수 있습니다.
Completion strategies: 수집 후 원천 파일 삭제
Completion strategies는 기존 기능 유지 단계(Legacy)입니다. 기존 동기화의 설정은 조회만 할 수 있고 수정할 수 없으며, 새 동기화에는 추가할 수 없습니다. 이미 설정된 동기화는 계속 동작합니다. 이 기능은 에이전트 워커 소스에서만 제공되던 방식이며 원천 파일시스템의 쓰기 권한이 필요합니다.
성공적인 수집 뒤 원천의 파일과 빈 상위 디렉터리를 삭제하려고 시도합니다. 중간 파일 저장소를 통해 데이터를 받는 구성에 사용할 수 있었지만 이런 중간 적재 방식 자체는 권장되지 않습니다. 가능하면 업무의 기준 데이터를 보유한 시스템에 직접 연결하고, Foundry가 기준 저장소라면 데이터를 중간 위치가 아니라 Foundry로 직접 보내는 방식을 사용합니다.
삭제는 보장되지 않음
기존 Completion strategies는 최선 노력 방식으로 동작합니다. 다음 경우에는 수집이 성공해도 원천 삭제가 이루어지지 않을 수 있습니다.
- Foundry에 데이터를 커밋한 뒤 삭제를 실행하기 전에 에이전트 워커가 중단되거나 재시작한 경우. 삭제 작업을 다시 시도하지 않습니다.
- 소스 인증 정보에 쓰기 권한이 없는 경우. 데이터를 읽어 커밋하는 작업은 성공해도 삭제는 실패할 수 있습니다.
사용자 지정 Completion strategies는 더 이상 지원되지 않습니다.
후속 외부 연결 변환으로 처리
대안은 동기화 출력 데이터셋이 갱신된 뒤 실행하는 외부 연결 변환(External transform)입니다. 가상의 S3 버킷에 foo.txt, bar.txt가 있고, Foundry로 가져온 뒤 이 두 파일을 원천에서 삭제해야 한다고 가정하겠습니다.
- Completion strategies 없이 배치 동기화를 구성하고 예약합니다.
- 수집 결과 데이터셋을 입력으로 받는 외부 연결 변환을 만듭니다.
- 데이터셋이 갱신되면 그 변환이 실행되도록 예약합니다.
- 변환에서 수집된 파일을 확인하고 S3의 해당 파일을 삭제하는 요청을 수행합니다.
이렇게 분리하면 Foundry에 데이터가 성공적으로 커밋된 뒤에만 삭제를 시도하고, 삭제 요청 실패를 다시 시도할 수 있습니다. 증분 파일 배치 동기화와도 함께 사용할 수 있습니다. Directory 소스에서 확실한 삭제 처리가 필요하다면 외부 연결 변환에서 SSH를 사용하는 방식도 고려할 수 있습니다.
파일 수가 많을 때의 구성
현재 동기화가 안정적으로 동작한다면 설정을 바꿀 필요는 없습니다. 새 동기화를 만들거나 큰 파일 집합 때문에 느리고 불안정한 경우에는 실행 단위를 나누는 방법을 검토합니다.
파일 집합이 계속 커지는 상황에서 SNAPSHOT은 매번 전체 데이터를 다시 수집합니다. 새 파일만 추가되는 원천에서는 다음 구성이 권장됩니다.
- 트랜잭션 유형:
APPEND. - 이미 가져온 파일 제외: Exclude files already synced.
- 한 번에 가져올 파일 수 제한: Limit number of files.
- 원천의 변경을 따라갈 수 있는 예약 실행.
파일 필터는 기본으로 적용되지 않으므로 APPEND를 선택할 때 중복 경로의 재수집을 막는 조건도 설정해야 합니다. 작은 배치가 각각 커밋되면 실패했을 때 현재 배치만 다시 가져오면 되며, 이미 커밋한 이전 배치를 반복해서 수집할 필요가 줄어듭니다.