Skip to content

클라우드 데이터 수집: SQL 편집기

이 페이지에서는 Braze 클라우드 데이터 수집(CDI) SQL 편집기를 사용하여 SQL 쿼리로 동기화를 생성하고 검증하는 방법을 다룹니다.

클라우드 데이터 수집의 SQL 편집기를 사용하면 데이터 웨어하우스에 대해 SQL 쿼리를 직접 작성하여 동기화를 생성할 수 있습니다. 이를 통해 전용 CDI 테이블을 생성하거나 유지 관리할 필요가 없어지며, 이전에는 데이터 웨어하우스 통합의 1.1단계에서 이 작업이 필요했습니다.

SQL 편집기는 다음과 같은 경우에 사용합니다:

  • 업스트림 테이블을 수정하지 않고 데이터를 동기화하려는 경우
  • 데이터 웨어하우스의 원시 데이터로 작업하려는 경우
  • PAYLOAD 열을 구성하지 않으려는 경우
  • SQL을 사용하여 더 복잡한 데이터 사용 사례를 처리하려는 경우

필수 조건 및 제한 사항

베타 기간 동안 SQL 편집기에는 다음과 같은 제한 사항이 있습니다:

  • 사용자 속성 동기화에만 사용 가능
  • 하나의 데이터 웨어하우스 소스 지원: Snowflake

새 SQL 편집기 동기화 생성

SQL 편집기로 동기화를 생성하려면 다음 단계를 따르세요. CDI용 Snowflake 소스를 이미 설정한 경우 3단계로 건너뛰세요.

1단계: Snowflake 역할, 권한, 데이터 웨어하우스 및 사용자 설정

CDI에서 Snowflake 소스를 생성하기 전에, Braze가 사용하는 Snowflake 사용자가 쿼리하려는 데이터에 대한 액세스 권한과 쿼리를 실행할 데이터 웨어하우스를 갖고 있는지 확인하세요.

1.1단계: (선택 사항) 데이터베이스 및 스키마 생성

필요한 경우 CDI 데이터를 위한 전용 데이터베이스와 스키마를 생성합니다:

1
2

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;

1.2단계: 역할 및 데이터베이스 권한 설정

동기화하려는 테이블에 대한 액세스 권한을 부여합니다:

1
2
3
4
5

CREATE ROLE BRAZE_INGESTION_ROLE;

GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.MY_USER_TABLE TO ROLE BRAZE_INGESTION_ROLE;

사용 사례에 따라 여러 테이블이나 향후 테이블에 대한 액세스 권한을 부여할 수도 있습니다. 예를 들어, 스키마의 모든 향후 테이블에 대한 액세스 권한을 부여하려면:

1

GRANT SELECT ON FUTURE TABLES IN SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;

1.3단계: 데이터 웨어하우스 설정 및 Braze 역할에 액세스 권한 부여

Braze가 쿼리를 실행할 데이터 웨어하우스를 생성합니다:

1
2

CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;

1.4단계: Snowflake 사용자 생성

Braze용 사용자를 생성하고 역할을 할당합니다:

1
2

CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

Braze에서 Snowflake 소스를 구성할 때 이 사용자를 사용합니다.

2단계: Braze 대시보드에서 새 소스 생성

이 단계에서는 Braze에서 Snowflake 소스를 생성하고 연결을 검증합니다.

2.1단계: Snowflake 소스 추가

  1. Braze 대시보드에서 데이터 설정 > 클라우드 데이터 수집 > 소스로 이동합니다.
  2. 데이터 소스 추가를 선택합니다.
  3. Snowflake를 선택합니다.

2.2단계: 연결 세부 정보 입력

소스의 이름을 선택하고 Snowflake 자격 증명 및 구성을 입력합니다.

2.3단계: RSA 키 설정 완료

자격 증명과 구성을 입력한 후 Save credentials를 선택하고 RSA 키를 생성합니다. 그런 다음 Snowflake로 돌아가서 설정을 완료합니다. 대시보드에 표시된 공개 키를 Braze가 Snowflake에 연결하기 위해 생성한 사용자에게 추가합니다.

자세한 내용은 Snowflake 키 쌍 인증을 참조하세요. 키를 교체하려면 Braze에서 새 키 쌍을 생성하고 새 공개 키를 제공할 수 있습니다.

1

ALTER USER BRAZE_INGESTION_USER SET RSA_PUBLIC_KEY='MIIBIjANBgkqhkiG9w0BA...';

Braze로 돌아가서 Test connection을 선택하여 소스 액세스를 확인한 다음 소스를 생성합니다.

3단계: 새 동기화 생성 및 SQL 쿼리 작성

  1. 데이터 설정 > 클라우드 데이터 수집 > 동기화로 이동합니다.
  2. Create data sync를 선택합니다.
  3. 데이터 유형에서 User Attributes를 선택합니다.
  4. 2단계에서 생성한 Snowflake 소스를 참조합니다.
  5. SQL을 선택하고 데이터 웨어하우스에서 사용자 데이터를 반환하는 SQL 쿼리를 작성합니다. SQL 쿼리는 Braze에 동기화할 데이터를 정의합니다. 쿼리 결과가 동기화의 스키마가 됩니다.

SQL이 선택되고 SQL 편집기에 샘플 쿼리가 표시된 데이터 동기화 생성 흐름.

SQL 쿼리는 다음을 반환해야 합니다:

  • 사용자 식별자 (EXTERNAL_ID, BRAZE_ID, ALIAS_NAME 및 ALIAS_LABEL, EMAIL, 또는 PHONE)
  • UPDATED_AT 열
  • 최소 하나의 추가 열 (속성)

4단계: 쿼리 미리보기 및 검증

Preview and validate를 선택하여 쿼리를 실행합니다.

미리보기:

  • 결과를 테이블 형식으로 표시합니다
  • 최대 100개 행을 표시합니다
  • 최대 250개 열을 표시합니다

계속하기 전에 쿼리를 성공적으로 미리보기하고 검증해야 합니다. 오류 및 수정 사항에 대한 자세한 내용은 검증 동작 및 문제 해결을 참조하세요.

5단계: 속성 매핑 검토 및 동기화 생성

검증 후:

  • 식별자 열이 사용자를 매칭합니다
  • UPDATED_AT 열이 증분 동기화를 구동합니다
  • Braze가 다른 모든 열을 속성으로 동기화합니다

검증이 성공하면 Next: Notifications로 계속 진행하여 동기화를 생성합니다.

SQL 제약 조건

쿼리는 다음 요구 사항을 충족해야 합니다.

사용자 식별자 포함

쿼리에는 다음 중 하나 이상이 포함되어야 합니다:

  • EXTERNAL_ID
  • BRAZE_ID
  • EMAIL
  • PHONE
  • ALIAS_NAME 및 ALIAS_LABEL

유효한 식별자가 감지되지 않으면 검증이 실패합니다.

UPDATED_AT 포함

쿼리에는 UPDATED_AT 열이 포함되어야 합니다.

UPDATED_AT은 대소문자를 구분하며 대문자여야 합니다.

누락된 경우 검증이 실패합니다.

최소 하나의 속성 열 포함

쿼리에는 다음 외에 최소 하나의 열이 포함되어야 합니다:

  • 사용자 식별자 열
  • UPDATED_AT

그렇지 않으면 검증이 실패합니다.

SELECT 쿼리만 사용

읽기 전용 쿼리만 지원됩니다.

사용할 수 있는 항목:

  • SELECT
  • WITH (CTE)
  • JOIN

사용할 수 없는 항목:

  • INSERT, UPDATE, 또는 DELETE
  • CREATE 또는 DROP
  • ;로 구분된 여러 문

단일 문 사용

쿼리는 단일 실행 가능한 문이어야 합니다.

검증 동작

SQL 편집기는 진행하기 전에 쿼리를 검증합니다.

SQL 오류

쿼리에 구문 오류가 포함된 경우:

  • 검증이 실패합니다
  • 미리보기가 표시되지 않습니다
  • 데이터 웨어하우스에서 오류 메시지를 반환합니다

컴파일 오류

쿼리가 유효하지 않은 테이블, 열 또는 권한이 없는 오브젝트를 참조하는 경우:

  • 검증이 실패합니다
  • 미리보기가 표시되지 않습니다
  • 데이터 웨어하우스에서 오류 메시지를 반환합니다

연결 오류

Braze가 데이터 웨어하우스에 연결할 수 없는 경우:

  • 검증이 실패합니다
  • 미리보기가 표시되지 않습니다
  • 연결 오류 메시지가 표시됩니다

쿼리 시간 초과

쿼리가 너무 오래 실행되는 경우:

  • Braze가 쿼리를 종료합니다
  • 검증이 실패합니다
  • 시간 초과 오류가 표시됩니다

필수 열 누락

쿼리가 컴파일되더라도 다음과 같은 경우 검증이 실패할 수 있습니다:

  • 식별자 열이 발견되지 않은 경우
  • UPDATED_AT이 누락된 경우
  • 속성 열이 없는 경우

이 경우 성공적인 검증을 위해 미리보기가 계속 표시됩니다.

결과가 0행인 경우

쿼리가 0행을 반환하는 경우:

  • 검증이 통과합니다
  • 동기화를 계속 생성할 수 있습니다
  • 행이 반환될 때까지 사용자가 업데이트되지 않습니다

PAYLOAD 지원 (레거시)

SQL 편집기는 PAYLOAD 열이 있는 레거시 CDI 테이블을 지원합니다.

쿼리에 다음이 포함된 경우:

  • 유효한 식별자
  • UPDATED_AT
  • PAYLOAD 열
  • 추가 열

그러면:

  • Braze는 PAYLOAD 열만 동기화합니다
  • Braze는 추가 열을 무시합니다

SQL 동기화 편집

기존 동기화를 편집할 때:

  • SQL 변경 사항은 재검증이 필요합니다
  • 유효하지 않은 변경 사항은 저장할 수 없습니다
  • 유효한 변경 사항은 저장 후 적용됩니다

동기화 실행이 이미 진행 중인 경우 변경 사항은 다음 실행에 적용됩니다.

문제 해결

이 섹션에는 일반적인 오류와 문제 해결 방법이 포함되어 있습니다.

미리보기를 사용할 수 없음

“미리보기를 사용할 수 없음”이 표시되면 다음 기본 오류 유형 중 하나가 원인일 수 있습니다.

오류 유형 해결 단계
“미리보기를 사용할 수 없음” 오류 배너에서 힌트를 확인하세요.
“소스에 연결할 수 없음” 구성된 사용자 이름, 계정 로케이터 및 RSA 키 쌍 인증 설정을 확인하세요.
데이터 웨어하우스가 실행 중인지 확인하세요.
네트워크 액세스를 확인하세요.
“SQL 구문 오류” SQL 구문을 확인하세요.
“오브젝트가 존재하지 않거나 권한이 없음” 역할에 테이블에 대한 SELECT 액세스 권한이 있는지 확인하세요.
데이터베이스 및 스키마 권한을 확인하세요.
테이블 이름 오타를 확인하세요.

식별자 열 필수

쿼리에 external_id와 같은 유효한 식별자가 포함되어 있는지 확인하세요.

UPDATED_AT 열 누락

증분 동기화를 위한 타임스탬프 열을 추가하세요.

동기화할 속성 없음

식별자와 UPDATED_AT 외에 최소 하나의 추가 열을 추가하세요.

쿼리 실행 시간 초과

쿼리를 최적화하거나 더 큰 데이터 웨어하우스를 사용하세요.
New Stuff!