Klaviyo 데이터를 Databricks로 내보내는 방법

학습 내용

Klaviyo가 아웃바운드 동기화 대상(Destination)으로 Databricks를 설정해 자체 Databricks 워크스페이스의 Delta 테이블에 프로필, 이벤트 및 지표 데이터를 지속적으로 작성하도록 설정하는 방법을 알아보세요. 연결되면 데이터 팀이 분석, 모델링 및 보고를 위해 Klaviyo 데이터와 나머지 레이크하우스 데이터를 조인할 수 있어요.

대신 Databricks에서 Klaviyo로 데이터를 가져오고 싶으신가요? Klaviyo와 Databricks 연결을 참고해 주세요.

시작하기 전에 알아야 할 것

다음 사항이 있는지 확인해 주세요:

• Unity Catalog가 활성화된 Databricks 워크스페이스. Hive metastore만 사용하는 워크스페이스는 지원되지 않아요. Hive metastore를 사용 중이라면 Hive metastore federation을 고려해 보세요.
• Klaviyo가 데이터를 쓸 수 있도록 VARIANT 개 열과 세션 범위 임시 테이블을 지원하는 SQL 웨어하우스 예요. 서버리스 SQL 웨어하우스를 권장해요. Classic 및 Pro 웨어하우스는 시작하는 데 몇 분이 걸릴 수 있어 동기화가 지연될 수 있어요.
• 사용할 카탈로그에서 스키마, 테이블, 권한 부여를 생성할 수 있는 권한(또는 Databricks 관리자 도움).
• Klaviyo에서 연동을 관리할 수 있는 권한입니다.
• IP 액세스 목록으로 작업 공간의 인바운드 트래픽을 제한하는 경우 Klaviyo의 아웃바운드 IP 주소를 허용 목록에 추가했는지 확인해 주세요:
  • 184.72.183.187/32
  • 52.206.71.52/32
  • 3.227.146.32/32
  • 44.198.39.11/32
  • 35.172.58.121/32
  • 3.228.37.244/32
  • 54.88.219.8/32
  • 3.214.211.176/32

1단계: Klaviyo 데이터용 스키마 만들기

Databricks에서는 스키마가 카탈로그 안에 있어요. Klaviyo가 데이터를 쓰는 테이블을 저장할 전용 스키마를 만드세요. 이 문서 전반의 SQL 예시에서는 카탈로그로 main을(를), 스키마로 KLAVIYO_EXPORT을(를) 사용해요. 다른 이름을 사용하는 경우, 모든 SQL 예시에서 해당 이름으로 바꾸고 5단계에서 Klaviyo에도 동일한 이름을 입력해 주세요.

USE CATALOG main;  -- or your organization's designated catalog
CREATE SCHEMA IF NOT EXISTS KLAVIYO_EXPORT;

2단계: 대상 테이블 만들기

1단계에서 생성한 스키마에서 다음 스크립트를 실행해 주세요. Klaviyo는 3개의 테이블에 씁니다:

• klaviyo_profile: 표준 필드, 위치, 사용자 지정 속성을 포함하여 프로필당 1행입니다.
• klaviyo_event: 이벤트(예: Placed Order 또는 Opened Email)당 1개 행으로, 프로필 및 지표에 연결돼요.
• klaviyo_metric: 지표당 1개 행으로, 각 이벤트의 지표 이름과 소스 연동을 조회하는 데 사용돼요.

사용자 지정 프로필 속성과 이벤트 속성은 VARIANT 열에 저장되므로, 개별 열을 수백 개 관리하지 않고도 중첩된 JSON을 직접 쿼리할 수 있어요.

USE SCHEMA main.KLAVIYO_EXPORT;

CREATE TABLE klaviyo_profile (
  id                 STRING NOT NULL,
  external_id        STRING,
  email              STRING,
  phone_number       STRING,
  first_name         STRING,
  last_name          STRING,
  title              STRING,
  organization       STRING,
  properties         VARIANT,
  image              STRING,
  created            TIMESTAMP,
  updated            TIMESTAMP,
  location_address1  STRING,
  location_address2  STRING,
  location_city      STRING,
  location_country   STRING,
  location_latitude  STRING,
  location_longitude STRING,
  location_region    STRING,
  location_zip       STRING,
  PRIMARY KEY (id)
)
TBLPROPERTIES ('delta.feature.variantType-preview' = 'supported');

CREATE TABLE klaviyo_event (
  id               STRING NOT NULL,
  metric_id        STRING NOT NULL,
  profile_id       STRING,
  event_properties VARIANT,
  datetime         TIMESTAMP,
  uuid             STRING,
  PRIMARY KEY (id)
)
TBLPROPERTIES ('delta.feature.variantType-preview' = 'supported');

CREATE TABLE klaviyo_metric (
  id                   STRING NOT NULL,
  name                 STRING NOT NULL,
  integration_id       STRING,
  integration_name     STRING,
  integration_category STRING,
  created              TIMESTAMP,
  updated              TIMESTAMP,
  PRIMARY KEY (id)
);

3단계: 서비스 프린시펄과 액세스 토큰 생성

Klaviyo는 개인 액세스 토큰(PAT)으로 Databricks에 인증해요. 개인 계정보다는 이 연동에만 사용하는 전용 서비스 프린시펄을 생성하는 것을 권장해요.

1. Klaviyo용 서비스 프린시펄 (또는 작업 공간 사용자)을 생성해 주세요.
2. 개인 액세스 토큰을 생성하세요:
   • 서비스 주체: 워크스페이스 관리자에게 Databricks CLI로 초기 토큰을 생성해 달라고 요청해 주세요.
   • 워크스페이스 사용자: Databricks UI에서 토큰 만들기.
3. 토큰을 안전한 곳에 저장해 주세요. 5단계에서 Klaviyo에 붙여넣을 거예요.

Databricks에서 가져오기를 위해 이미 서비스 프린시펄을 생성했다면 재사용할 수 있습니다. 4단계에서 내보내기 권한을 추가하기만 하면 됩니다.

4단계: 권한 부여

Klaviyo 서비스 프린시펄에 카탈로그, 스키마 및 SQL 웨어하우스에 대한 액세스 권한을 부여하세요. klaviyo_service_user을(를) 서비스 프린시펄의 애플리케이션 ID 또는 사용자 이름으로 바꾸세요.

GRANT USE CATALOG ON CATALOG main TO `klaviyo_service_user`;
GRANT USE SCHEMA, SELECT, MODIFY ON SCHEMA main.KLAVIYO_EXPORT TO `klaviyo_service_user`;

또한 사용할 예정인 SQL 웨어하우스에 서비스 프린시펄의 사용 가능 권한도 부여하세요. Databricks에서 SQL Warehouses로 이동해 웨어하우스를 선택한 다음 Permissions를 클릭하고 서비스 프린시펄을 추가하세요.

설정 확인(선택 사항)

Klaviyo에 제공할 동일한 ID와 토큰을 사용해 테이블과 권한 부여를 확인하세요.

SHOW TABLES IN main.KLAVIYO_EXPORT;
SHOW GRANTS ON SCHEMA main.KLAVIYO_EXPORT;

3개 테이블이 모두 표시되고, 서비스 프린시펄이 USE SCHEMA, SELECT, MODIFY와 함께 나열되어야 해요.

5단계: Klaviyo에서 Databricks 연결

1. Klaviyo에서 고급 > 데이터 관리 > 동기화로 이동합니다.
2. 이미 동기화가 있다면 동기화 만들기를 클릭해 주세요.
3. 데이터 웨어하우스로 데이터 내보내기를 선택하세요.
4. Databricks를 선택한 다음 Databricks에 연결을 클릭하세요.
5. 연결 세부 정보를 입력해 주세요:

동기화를 구성하려면 다음을 클릭하세요.

또한 연동 > 앱 탐색으로 이동한 다음 Databricks를 검색해 Klaviyo의 앱 마켓플레이스에서 Databricks를 찾을 수도 있어요.

6단계: 데이터 동기화를 구성하세요

Klaviyo에서 Databricks로 무엇을 전송할지와 동기화 시점을 선택해 주세요.

데이터 개체

프로필, 이벤트 또는 둘 다를 동기화하도록 선택합니다. 지표 데이터는 이벤트와 함께 동기화되므로 각 이벤트의 지표 이름과 소스를 조회할 수 있어요.

제외할 연동 서비스

Databricks로 전송하지 않을 이벤트가 있는 연동을 선택하세요. 이 설정은 이벤트 데이터에만 적용되며 프로필은 제외하지 않습니다.

선택적 동기화

Placed Order 같은 동기화할 이벤트의 지표를 선택하세요. 제외하지 않은 연동의 모든 이벤트를 동기화하려면 선택적 동기화를 비워 두세요. 이 필드는 이벤트 데이터 개체를 선택한 경우에만 표시돼요.

동기화 케이던스

Every에서 새 데이터와 업데이트된 데이터를 얼마나 자주 동기화할지 선택해 주세요. 1, 2, 4, 6, 12 또는 24시간마다로 설정할 수 있어요. 기본값은 1시간이에요. 일정에 사용할 Start Date, Start Time, Timezone을 설정해 주세요.

과거 데이터

초기 동기화 중에 전송할 과거 데이터의 양을 선택하세요.

• 30일
• 90일
• 1년
• 모든 시간

7단계: 동기화 검토, 연결 및 모니터링

1. 다음을 클릭해 검토를 여세요. 연결 세부정보, 공유된 데이터, 제외된 연동, 선택한 지표, 초기 데이터 동기화 범위를 확인해 주세요.
2. 연결을 클릭합니다. Klaviyo는 연결을 테스트하고, 테스트가 성공하면 내보내기를 생성합니다.

설정이 성공하면 Klaviyo에서 확인 메시지가 표시되고 동기화 중으로 돌아가요. 내보내기가 활성화되어 있고, 여기에서 동기화 상태를 모니터링할 수 있어요.

연결 테스트에 실패하면 오류 세부 정보를 확인해 주세요. 연결 정보를 수정하려면 자격 증명 편집을 클릭한 다음, 데이터 설정에서 다음을 클릭해 검토로 돌아가서 연결을 다시 클릭해 주세요.

동기화를 모니터링하려면 고급 > 데이터 관리 > 동기화로 이동한 다음, 내보내기로 표시된 행에서 Databricks를 클릭해 주세요. 다음 탭을 사용하세요:

• 과거: 초기 백필 상태입니다.
• 주기적: 선택한 주기에 따라 동기화 상태를 보여 주며, 데이터 신선도 (Databricks 테이블이 Klaviyo보다 얼마나 뒤처져 있는지)도 포함해요.
• 설정: 연결 세부 정보, 데이터 선택, 동기화 주기, 과거 범위를 확인하고 수정할 수 있어요. 변경한 섹션에서 정보 업데이트를 클릭해 저장하세요.

동기화 상태, 동기화 일시 중지 및 재개, 오류 로그 보기의 자세한 내용은 Klaviyo에서 데이터 웨어하우스 동기화 이해하기를 참고하세요.

Databricks에서 Klaviyo 데이터 쿼리하기

시작할 수 있도록 몇 가지 예시를 준비했어요.

지난 7일 동안 지표 이름별 이벤트 수 집계:

SELECT m.name AS metric, COUNT(*) AS events
FROM main.KLAVIYO_EXPORT.klaviyo_event e
JOIN main.KLAVIYO_EXPORT.klaviyo_metric m ON e.metric_id = m.id
WHERE e.datetime >= current_timestamp() - INTERVAL 7 DAYS
GROUP BY m.name
ORDER BY events DESC;

properties 같은 이메일의 다른 버전 열에서 사용자 지정 프로필 속성 읽기:

SELECT id, email, properties:loyalty_tier::STRING AS loyalty_tier
FROM main.KLAVIYO_EXPORT.klaviyo_profile
WHERE properties:loyalty_tier IS NOT NULL;

Placed Order 이벤트에서 주문 금액 가져오기:

SELECT e.profile_id, e.datetime, e.event_properties:`$value`::DOUBLE AS order_value
FROM main.KLAVIYO_EXPORT.klaviyo_event e
JOIN main.KLAVIYO_EXPORT.klaviyo_metric m ON e.metric_id = m.id
WHERE m.name = 'Placed Order';

문제 해결

Databricks 내보내기 제거

내보내기를 제거하면 이후 동기화가 중지돼요. 이미 Databricks 테이블에 기록된 데이터는 삭제되지 않아요.

1. Klaviyo에서 연동으로 이동해 주세요.
2. Databricks 내보내기 연동 옆의 메뉴를 열고 연동 제거를 선택해 주세요.
3. 확인 대화상자에서 연동 제거를 클릭해 주세요.

추가 자료

• Klaviyo와 Databricks 연결 (가져오기)
• Klaviyo의 데이터 웨어하우스 동기화 이해하기
• Klaviyo 고급 데이터 플랫폼 시작하기