Databricks 데이터 소스 설정
Databricks 데이터 소스는 오프라인 동기화를 통해 Databricks와 플랫폼의 기본 스토리지 간에 테이블 데이터를 전송하는 데 사용됩니다. 이 문서에서는 Databricks-JDBC 연결 설정, 소스 및 목적지 설정, 지원하는 필드 타입, 동기화 검증과 워크플로우 스케줄을 설명합니다.
사용 제한 및 사전 준비
설정을 시작하기 전에 다음 사항을 확인하십시오.
- Databricks → 기본 스토리지 및 기본 스토리지 → Databricks를 지원합니다. 이 계획에서는 Databricks와 다른 외부 데이터 소스 간의 직접 전송을 지원하지 않습니다.
- Databricks에서 JDBC 연결에 사용할 컴퓨팅 리소스를 준비하고 해당 JDBC URL과 Personal Access Token을 확보합니다. 연결 정보는 실제 사용하는 컴퓨팅 리소스, 워크스페이스 및 드라이버 설정과 일치해야 합니다. Databricks JDBC 연결 설명을 참조하십시오.
- Token을 소유한 계정에는 해당 컴퓨팅 리소스를 사용하고, Catalog와 데이터베이스(Schema)에 접근하며, 테이블 메타데이터를 조회할 권한이 필요합니다. 소스 테이블을 읽으려면 읽기 권한이, 타겟 테이블에 쓰려면 해당 쓰기 권한이 필요합니다. Databricks 관리자가 실제 사용 범위에 맞게 권한을 부여해야 합니다.
- 플랫폼 실행 환경에서 JDBC URL에 해당하는 서비스에 접근할 수 있어야 합니다. Databricks에 네트워크 접근 제한이 설정되어 있으면 플랫폼 서버의 실제 아웃바운드 주소와 허용된 접근 범위를 확인하십시오.
- 타겟 테이블을 미리 준비하고 필드 타입 및 파티션 정의를 확인합니다. 기본 스토리지의 타겟 테이블 생성 방법은 워크스페이스 테이블 생성 및 관리를 참조하십시오. Databricks 타겟 테이블은 타겟 Catalog와 데이터베이스에 미리 준비해야 합니다.
| 환경 설정 방식 | 설정 요구 사항 |
|---|---|
| 환경 구분 없음 | 개발 환경과 운영 환경에서 하나의 연결 및 자격 증명 설정을 공유 |
| 독립 환경 설정 | 개발 환경과 운영 환경을 각각 설정. 두 설정 모두 계획에서 선택한 테이블에 접근할 수 있어야 함 |
데이터 미리보기는 개발 환경 설정을 사용하고 수동 실행은 운영 환경 설정을 사용합니다. 각 설정의 컴퓨팅 리소스, 테이블 권한 및 네트워크 접근을 확인하십시오.
Databricks 연결 정보 가져오기
- Databricks 워크스페이스에 로그인하고 연결할 컴퓨팅 리소스를 엽니다. 클러스터의 연결 정보는 Compute > 타겟 클러스터 > Configuration > Advanced options > JDBC/ODBC에서 확인할 수 있습니다. SQL 웨어하우스는 SQL Warehouses > 타겟 웨어하우스 > Connection details에서 확인할 수 있습니다.
- JDBC URL을 가져오고 그 안의 서비스 호스트, 포트 및 HTTP Path가 의도한 컴퓨팅 리소스를 가리키는지 확인합니다. 구체적인 위치는 Databricks JDBC 연결 설명을 참조하십시오.
- 해당 워크스페이스에서 사용할 수 있는 PAT를 준비합니다. 새로 생성해야 하는 경우 Settings > Developer > Access tokens > Manage에서 생성하고 적절한 유효 기간을 설정합니다. 생성하거나 사용할 수 없으면 워크스페이스 관리자에게 문의하십시오. 절차는 Databricks 개인용 액세스 토큰 생성을 참조하십시오.
Token은 안전한 방법으로 전달하고 스크린샷, 로그 또는 공개 문서에 자격 증명을 노출하지 마십시오. Token을 교체하거나 권한을 변경한 후에는 데이터 소스 연결과 동기화 계획을 다시 검증해야 합니다.
Databricks 데이터 소스 생성
- 데이터 개발 플랫폼 > 통합 > 데이터 소스로 이동하여 + 데이터 소스를 클릭합니다.
- Databricks-JDBC를 선택하고 다음을 클릭한 후 데이터 소스 이름과 비고를 입력합니다.
- 환경 구분 없음 또는 독립 환경 설정을 선택합니다. 독립 환경 설정에서는 개발 환경과 운영 환경의 정보를 각각 입력해야 합니다.
- 다음 연결 파라미터를 입력합니다. 연결 테스트에서 테스트를 클릭하고 테스트를 통과했는지 확인한 후 완료를 클릭합니다.
| 구성 항목 | 설명 |
|---|---|
| JDBC URL | Databricks 컴퓨팅 리소스에 해당하는 JDBC 연결 주소. 서비스 주소 및 연결 파라미터는 관리자에게 확인 |
| 인증 방식 | PAT 선택 |
| Personal Access Token | 접근 계정의 유효한 Token을 입력. 이번 읽기 또는 쓰기에 필요한 권한이 있어야 함 |
| 고급 설정 | 필요에 따라 JSON 형식의 확장 설정을 입력. 추가 설정이 필요하지 않으면 비워 둘 수 있음 |
연결 테스트를 통과한 후에도 동기화 계획에서 테이블을 불러오고 소스 데이터를 미리 본 다음 실행하여 실제 테이블 권한과 읽기 및 쓰기 결과를 검증해야 합니다.
Databricks 데이터 소스 설정
- 데이터 개발 플랫폼 > 통합 > 오프라인 동기화로 이동하여 + 통합 방안을 클릭합니다.
- 데이터 소스에서 Databricks-JDBC와 생성한 데이터 소스를 선택합니다.
- 데이터 가져오기 방식을 선택하고 전체 테이블 읽기 또는 사용자 정의 쿼리로 소스를 설정합니다.
- 데이터 미리보기를 클릭하여 소스 필드, 실제 값 및 읽기 범위를 확인합니다.
- 배치 크기를 조정하려면 고급 설정을 펼쳐 설정합니다.
그림은 기존 계획의 설정 예시이며 현재 연결 및 데이터 읽기 검증을 대신하지 않습니다. 설정을 완료한 후 데이터 미리보기를 사용하여 실제 결과를 확인하십시오.
| 데이터 가져오기 방식 | 설정 방법 |
|---|---|
| 전체 테이블 | Catalog, 데이터베이스(Schema), 데이터 테이블을 순서대로 선택. 일부 데이터만 읽으려면 데이터 필터링을 켜고 필터 조건을 입력 |
| 사용자 정의 쿼리 | 동기화할 필드를 반환하는 읽기 전용 SQL 쿼리를 입력하고 필터 조건을 쿼리에 포함. 이 방식에서는 전체 테이블 방식의 Catalog, 데이터베이스, 데이터 테이블 선택 항목이나 데이터 필터링을 별도로 설정하지 않음 |
전체 테이블 방식의 데이터 필터링은 읽기 범위를 제한합니다. 편집기에 WHERE status = 'active'와 같은 WHERE 절을 입력하고 전체 SELECT 쿼리는 입력하지 마십시오. 사용자 정의 쿼리에서는 SQL이 올바른 Catalog와 데이터베이스에 접근할 수 있고 반환 필드의 이름이 명확하며 타입을 인식할 수 있는지 확인해야 합니다.
배치 크기의 기본값은 1000이며 설정 범위는 1000–10000입니다. 데이터 소스, 데이터 가져오기 방식, Catalog, 데이터베이스 또는 데이터 테이블을 변경한 후에는 읽기 범위, 미리보기 결과 및 필드 매핑을 다시 확인하십시오. 소스 구조나 쿼리 결과가 변경된 경우에도 필드를 다시 분석하고 매핑을 확인해야 합니다.
데이터 목적지 설정
Databricks 데이터를 기본 스토리지로 읽기
데이터 목적지에서 플랫폼의 기본 스토리지를 선택한 후 타겟 워크스페이스 테이블을 선택합니다. 타겟 테이블이 아직 없으면 먼저 테이블로 이동하여 필요한 필드 및 파티션 정의에 따라 생성하십시오. 워크스페이스 테이블 생성 및 관리를 참조하십시오.
| 구성 항목 | 설명 |
|---|---|
| 타겟 테이블 | 이번 데이터를 받을 기본 스토리지의 워크스페이스 테이블 |
| 파티션 정보 | 타겟이 파티션 테이블이면 타겟 테이블 요구 사항에 따라 각 파티션 값을 입력. 공간 파라미터를 사용하여 실행 시 파티션을 설정할 수 있음 |
| 쓰기 모드 | 타겟 데이터 보존 요구 사항에 따라 새 데이터 삽입 또는 덮어쓰기를 선택하고 실행 전에 타겟 테이블과 타겟 파티션을 다시 확인 |
기본 스토리지 데이터를 Databricks에 쓰기
데이터 소스에서 기본 스토리지의 소스 테이블을 설정합니다. 데이터 목적지에서 Databricks-JDBC와 생성한 데이터 소스를 선택한 후 타겟 Catalog, 데이터베이스(Schema), 데이터 테이블을 순서대로 선택합니다.
| 구성 항목 | 설명 |
|---|---|
| 쓰기 테이블 | Databricks에 미리 준비되어 있고 접근 계정에 쓰기 권한이 있는 타겟 테이블 |
| 파티션 정보 | 화면에 타겟 파티션 필드가 표시되면 모든 파티션 값을 입력하고 실행 시 실제 값을 확인 |
| 쓰기 모드 | 새 데이터 삽입만 지원하며 타겟 테이블에 데이터를 추가. 재실행 전에 중복 레코드가 생성될 수 있는지 평가 |
| 사전 실행 구문 | 필요에 따라 동기화 시작 전에 타겟에서 실행할 SQL을 입력. 필요하지 않으면 비워 둘 수 있음 |
| 배치 크기 | 고급 설정에 위치. 기본값은 5000이며 설정 범위는 1–10000 |
사전 실행 구문은 타겟에서 실제로 실행됩니다. 실행에 실패하면 이번 동기화 작업은 제출되지 않습니다. 사전 실행 구문과 이후 데이터 쓰기가 동일한 트랜잭션에 속한다는 보장은 없으며, 이후 동기화가 실패해도 이미 실행된 사전 실행 구문이 자동으로 취소된다는 보장은 없습니다. 입력하거나 재시도하기 전에 타겟 환경, SQL이 데이터에 미치는 영향 및 반복 실행 결과를 확인하십시오.
Databricks 목적지는 추가 쓰기 모드만 제공하며 덮어쓰기나 업데이트 삽입 모드는 제공하지 않습니다. 사전 삭제 구문과 추가 쓰기를 전체 롤백이 가능한 덮어쓰기 작업으로 간주하지 마십시오.
필드 매핑 및 지원하는 필드 타입
소스와 목적지 설정을 완료한 후 필드 매핑에서 소스 필드와 타겟 필드의 대응 관계를 설정합니다. 필드를 개별적으로 선택하거나 동일 이름 매핑 또는 동일 행 매핑을 사용한 후 항목별로 확인할 수 있습니다. 하나의 타겟 필드는 하나의 소스 필드에만 대응할 수 있습니다.
그림은 기존 계획의 필드 대응 관계를 보여 주며, 실시간 연결 또는 이번 실행 검증을 통과했다는 의미는 아닙니다.
읽기를 지원하는 필드 타입
Databricks를 데이터 소스로 사용할 때 다음 필드 타입을 지원합니다. 타입 이름은 대소문자를 구분하지 않습니다. 파라미터 또는 중첩 구조가 있는 필드는 전체 정의도 확인해야 합니다.
| 타입 분류 | 지원하는 Databricks 필드 타입 |
|---|---|
| 불리언 | boolean |
| 정수 | tinyint, smallint, int, integer, bigint |
| 부동 소수점 및 고정 소수점 | float, double, decimal |
| 문자열 | string, varchar, char |
| 날짜 및 시간 | date, timestamp, timestamp_ntz |
| 복합 타입 | array, map, struct. 전체 구조 확인 필요 |
binary와 interval, void, variant 등 목록에 없는 타입 및 기타 인식되지 않는 타입은 지원하지 않습니다.
쓰기를 지원하는 필드 타입
Databricks를 데이터 목적지로 사용할 때 지원하는 Databricks 필드 타입은 위 표와 동일합니다. binary, 목록에 없는 타입 및 기타 인식되지 않는 타입은 지원하지 않습니다.
타겟 테이블은 미리 생성해야 합니다. 필드 타입이 지원되어도 모든 데이터가 타겟 필드의 전체 정의와 NULL 제약 조건을 충족하는 것은 아닙니다.
필드 타입 사용 제한
decimal(p,s),varchar(n),char(n)은 전체 정밀도, 소수 자릿수 및 길이 요구 사항을 확인해야 합니다.timestamp,timestamp_ntz는 실제 시간의 의미, 시간대 및 정밀도 요구 사항을 확인해야 합니다. 타입 이름만으로 결과가 예상과 일치한다고 판단할 수 없습니다.array<T>,map<K,V>,struct<...>는 필드 이름과 순서, NULL 제약 조건 및 중첩 수준을 포함한 요소, 키-값 또는 필드 정의를 확인해야 합니다. 최상위 타입이 지원되어도 모든 내부 구조가 지원되는 것은 아닙니다. 예를 들어array가 지원된다는 이유만으로array<binary>도 지원된다고 판단할 수 없습니다.- 소스 또는 타겟 테이블의 구조가 변경되면 필드를 다시 분석하고 필드 대응 관계를 확인하십시오. 데이터 미리보기에 필드가 표시되어도 해당 필드 타입의 동기화가 지원된다는 의미는 아닙니다.
저장, 검증 및 워크플로우 스케줄
동기화 결과 저장 및 검증
- 소스 테이블 또는 쿼리, 필터 범위, 타겟 테이블 및 파티션, 쓰기 모드, 사전 실행 구문 및 필드 매핑을 확인합니다. 먼저 소스의 데이터 미리보기를 사용하여 필드와 샘플 값을 확인합니다.
- 계획 이름, 담당자 및 비고를 입력하고 저장을 클릭합니다.
- 수동 실행을 클릭하고 팝업의 안내에 따라 실행 모드를 선택한 후 이번 파라미터 값을 확인하고 실행을 시작합니다. 수동 실행은 운영 환경 설정을 사용합니다. 실행 모드는 개발 환경과 운영 환경을 전환하는 용도가 아닙니다.
- 수동 실행 기록에서 상태와 로그를 확인합니다. 작업이 성공하면 타겟 테이블에서 데이터 양, 필드 대응 관계, 숫자, 시간, 복합 타입 및 NULL 등의 샘플을 확인합니다.
독립 환경 설정에서 개발 환경의 데이터를 불러오거나 미리 볼 수 있다고 해서 운영 환경의 자격 증명 및 읽기·쓰기 권한도 준비된 것은 아닙니다. 최초 실행 전에 두 설정과 타겟 환경의 테이블, 파티션 및 파라미터를 각각 확인하십시오. Databricks에 추가 쓰기를 하거나 사전 실행 구문을 설정할 때는 재시도가 기존 데이터에 미치는 영향도 평가해야 합니다.
작업 플로우에 연결
수동 검증을 통과한 후 계획을 작업 플로우에 연결하여 스케줄링 주기에 따라 실행할 수 있습니다.
- 저장된 계획을 열고 워크플로우에 연결을 클릭하여 타겟 작업 플로우를 선택합니다. 아직 생성하지 않은 경우 작업 플로우 생성을 참조하십시오.
- 노드 이름, 실행 모드, 담당자 등의 정보를 입력하고 노드 생성 및 연결을 클릭합니다.
- 작업 플로우로 이동을 클릭하고 노드와 상하위 종속성을 확인한 후 스케줄링에 사용되는 테이블, 파티션 및 공간 파라미터를 확인합니다.
- 작업 플로우 스케줄 설정을 완료하고 저장한 후 작업 플로우를 배포합니다. 연결에 성공했다고 해서 노드가 이미 배포되어 운영 중인 것은 아닙니다.
계획을 작업 플로우에 연결한 후에는 계획 상세 페이지에서 더 이상 수동 실행하지 않습니다. 작업 플로우에서 해당 노드를 실행하고 검증하십시오.
자주 묻는 질문
| 증상 | 확인 항목 |
|---|---|
| 연결 테스트 실패 | JDBC URL 및 PAT의 유효성, 컴퓨팅 리소스 접근 권한 및 플랫폼 서버의 네트워크 접근 범위를 확인 |
| 연결은 가능하지만 테이블을 찾을 수 없거나 미리 볼 수 없음 | Catalog, 데이터베이스 및 테이블 이름, 메타데이터 및 읽기 권한을 확인. 사용자 정의 쿼리는 SQL 및 접근 범위도 확인 |
| 미리보기는 정상이지만 실행 실패 | 운영 환경 자격 증명, 타겟 쓰기 권한, 테이블 및 파티션, 파라미터, 사전 실행 구문을 확인하고 실행 로그를 검토 |
| 재실행 후 중복 데이터 발생 | 추가 쓰기 범위와 이전 실행 결과를 확인하여 동일한 데이터 배치를 중복으로 읽고 썼는지 확인 |

