동기화와 에이전트 운영 FAQ

예약한 빌드가 실행되지 않음

예약 시각이 되었는데 실행을 시도하지 않았다면 다음 순서로 확인합니다.

1. 같은 데이터셋과 브랜치에서 다른 동기화가 실행 중인지 확인합니다. 같은 데이터셋과 브랜치에서 두 동기화를 동시에 실행할 수 없습니다.
2. 예약이 일시 중지되어 있는지 확인합니다. 동기화의 Edit in Scheduler 또는 Dataset Preview의 Manage Schedules에서 예약 개요를 볼 수 있습니다.
3. 에이전트를 사용하는 소스라면 연결된 에이전트가 비활성화되어 있지 않은지 확인합니다.

수집 결과에 중복 행이 생김

SNAPSHOT은 현재 데이터셋 뷰를 새로운 파일 집합으로 대체하는 트랜잭션입니다. 입력 파일이나 쿼리 결과 안의 중복 행을 자동으로 제거하는 기능은 아닙니다. APPEND는 기존 파일을 유지하면서 새 파일을 추가합니다.

목표가 새로 생긴 행만 계속 추가하는 증분 수집이라면, APPEND와 증분 기준 열을 함께 구성합니다. 예를 들어 가상의 last_upd_in_appl_ts 열이 각 행을 구분할 수 있고 항상 증가하는 값이라고 가정하겠습니다.

1. 새 동기화를 APPEND 유형으로 구성합니다.
2. 증분 설정의 기준 열을 last_upd_in_appl_ts로 지정합니다.
3. 첫 수집에 사용할 초기값은 그 열의 모든 값보다 작은 값으로 지정합니다.

이후 Data Connection은 마지막으로 수집한 값을 추적하고 그보다 큰 값을 가진 새 행을 가져옵니다. 타임스탬프라면 나중 시각이 더 큰 값입니다. 이 구성은 기준 열이 유일하고 계속 증가한다는 조건을 충족해야 합니다.

트랜잭션 유형을 바꾸는 것만으로 기존 중복 행이 사라지지는 않습니다. 전체 원천을 매번 다시 읽는 작업을 증분 조건 없이 APPEND로 실행하지 않도록 설정을 함께 확인합니다.

증분 실행에서 사용한 값 확인

특정 실행 건에서 사용한 증분 정보를 확인하려면 다음 경로를 사용합니다.

1. 출력 데이터셋을 엽니다.
2. 위쪽의 History를 선택합니다.
3. 왼쪽에서 조사할 트랜잭션을 선택합니다.
4. Build를 엽니다.
5. Transaction을 엽니다.
6. 아래쪽의 Custom Metadata를 펼칩니다.
7. incrementalMetadata의 값을 확인합니다.

데이터베이스와 데이터셋의 열 타입이 다름

TIMESTAMP가 LONG으로 들어옴

일부 데이터베이스 드라이버는 타입을 더 단순하고 안전한 표현으로 변환하여 전달할 수 있습니다. 원천 열이 TIMESTAMP인데 Foundry 결과가 LONG이라면 Code Repositories 등의 데이터 변환 도구로 해당 값을 적절한 TIMESTAMP로 파싱합니다.

시간대가 없는 타임스탬프는 동기화 설정에서도 처리 방식을 선택할 수 있습니다. 기본 문자열 처리, 시간대를 지정한 timestamp, long 선택은 배치 동기화의 테이블 전용 옵션에서 설명합니다.

DECIMAL 정밀도가 달라짐

원천 데이터베이스와 결과 데이터의 정밀도가 다르면 다음 방법을 사용할 수 있습니다.

• 원천 쿼리에서 원하는 정밀도와 소수 자릿수로 명시적으로 변환합니다.
• 원천 쿼리에서 VARCHAR로 변환하여 수집하고 Foundry에서 필요한 숫자 타입으로 다시 변환합니다.

TIME의 초 미만 정밀도가 사라짐

PostgreSQL과 Microsoft SQL Server를 포함한 대부분의 JDBC 기반 소스에서는 데이터베이스의 TIME을 자정 이후 경과한 밀리초를 나타내는 INTEGER로 기록하며, 초 미만 부분은 버립니다.

초 미만 차이를 보존하려면 수집 쿼리에서 문자열로 바꿀 수 있습니다. 다음은 가상의 PostgreSQL events 테이블에서 event_time을 문자열로 읽는 예시입니다.

SELECT event_id, CAST(event_time AS text) AS event_time
FROM events

실행 중인 쿼리의 상태 확인

Job tracker를 열고 실행 중인 동기화를 선택합니다. 이 화면에서 동기화의 세부 상태와 로그를 확인할 수 있습니다. 원천 데이터베이스에도 접근할 수 있다면 그쪽에서 실제 쿼리의 동작을 함께 확인합니다.

APPEND 사이에 스키마가 달라짐

증분 APPEND 실행 사이에 파일이나 JDBC 테이블의 스키마가 바뀌면 스키마 불일치로 실패할 수 있습니다. Data Connection은 JDBC 추출에서 스키마를 추론하지만, 파일 기반 추출에서는 기존 스키마를 전파합니다.

스키마를 다시 추론했을 때 이전과 같다면 기존 데이터셋을 계속 사용할 수 있습니다. 실제 스키마가 달라 기존 데이터와 함께 추가할 수 없다면 새 스키마를 위한 데이터셋을 별도로 준비합니다.

동기화 실패로 트랜잭션이 중단된 경우에는 해당 실행의 데이터가 커밋되지 않습니다. 반면 새 스키마의 데이터가 이미 추가되어 결과 해석에 문제가 생긴 경우에는 커밋된 트랜잭션의 복구를 검토해야 합니다.

파일 기반 동기화

1. XLSX 또는 CSV 테이블 파일이라면 동기화된 데이터셋의 스키마를 다시 추론할 수 있는지 확인합니다.
2. 다시 추론한 스키마가 기존과 같으면 추가한 행을 정상적으로 읽을 수 있습니다.
3. 여전히 스키마 오류가 난다면 새 파일을 다른 스키마의 테이블로 취급하고 새 데이터셋에 수집합니다.
4. 문제가 있는 새 스키마의 데이터가 이미 기존 데이터셋에 추가되었다면 예약 실행을 일시 중지하고 Palantir 지원팀에 해당 트랜잭션의 복구를 요청합니다.
5. 기존 동기화의 설정을 새 동기화로 복사하되 출력은 새 데이터셋으로 바꿉니다. 이름에 스키마 버전을 표시하면 구분하기 쉽습니다.
6. 새 스키마의 파일이 계속 이전 데이터셋에 들어가지 않도록 기존 동기화의 사용을 중단하거나 필요에 따라 제거합니다.

JDBC 동기화

스키마가 바뀔 가능성이 있고 변경된 형태를 계속 사용할 예정이라면 account_transactions_v1.0처럼 데이터셋 이름에 스키마 버전을 표시할 수 있습니다.

원천 테이블이 바뀌었지만 아직 동기화하지 않았다면 먼저 예약을 일시 중지합니다. 이미 실행하여 기존 대상에 잘못된 스키마의 데이터가 들어갔다면 예약을 중지하고 Palantir 지원팀에 해당 트랜잭션의 복구를 요청합니다.

새 스키마를 적용할 준비가 되면 다음과 같이 전환합니다.

1. 기존 동기화를 복제합니다.
2. 출력을 account_transactions_v1.1 같은 새 데이터셋으로 지정합니다.
3. 새 동기화가 올바르게 동작하는지 확인합니다.
4. 필요한 경우 기존 데이터셋과 새 데이터셋을 후속 변환에서 결합하여 전체 데이터를 구성합니다.

기존 동기화를 제거하면 이전 데이터셋에 잘못된 데이터가 다시 들어가는 위험을 줄일 수 있지만, 과거 수집 설정을 확인하기는 어려워집니다. 기존 설정의 보존 필요성과 재실행 위험을 함께 고려합니다.

삭제한 동기화 작업 명세를 다시 추가하면 권한 오류가 남

삭제한 작업 명세(Job spec)를 다시 추가할 때 권한 오류가 발생하면, 같은 데이터셋을 출력으로 사용하는 새 동기화를 만듭니다. 이렇게 하면 기존 데이터셋을 유지하면서 올바른 권한을 가진 새 작업 명세를 만들 수 있습니다.

새 동기화를 실행하면 선택한 트랜잭션 유형에 따라 기존 데이터를 덮어쓸 수 있으므로, 실행 전에 출력 대상과 SNAPSHOT, APPEND 설정을 확인합니다.

Bootvisor가 Unknown에 머무름

Bootvisor가 Unknown 상태에서 시작하거나 중지되지 않으면 먼저 Palantir 지원팀에 구성을 확인받습니다. 아래 절차는 해당 에이전트에 의존하는 동기화를 일시적으로 실행하지 못하게 하므로, 다중 에이전트로 가용성을 확보하거나 유지보수 시간대에 수행해야 합니다.

1. 해당 에이전트의 동기화를 일시 중지합니다.
2. 이미 실행 중인 동기화가 모두 끝날 때까지 기다립니다.
3. 에이전트를 중지합니다. 현재 상태에 따라 중지 요청이 실패할 수 있습니다.
4. 에이전트 호스트에 SSH로 접속합니다.
5. Data Connection과 관련된 JVM 프로세스를 식별하여 종료합니다. 다른 애플리케이션의 Java 프로세스를 함께 종료하지 않습니다.
6. 에이전트 설치 디렉터리에서 Bootvisor를 시작합니다.

./service/bin/init.sh start

7. Data Connection 화면에서 에이전트를 시작하고 일시 중지 상태도 해제되어 있는지 확인합니다.

TLS와 인증서 오류

서버 인증서와 클라이언트 인증서의 구분, CERTIFICATE_VERIFY_FAILED와 같은 인증서 체인 문제는 소스 연결과 인증 문제 조사에서 설명합니다. 연결에 사용할 수 있는 암호 스위트는 TLS 지원 범위에서 확인할 수 있습니다.