이 페이지는 AI로 자동 번역되었으며 부정확한 내용이 포함될 수 있습니다. 번역 오류를 신고하려면 페이지 오른쪽 목차 아래에 있는 피드백 기능을 사용하세요.

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

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

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

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

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

사전 요구 사항 및 제한 사항

SQL 편집기에는 다음과 같은 제한 사항이 있습니다.

데이터 웨어하우스 소스에서만 사용할 수 있습니다: Snowflake, Redshift, BigQuery, Databricks, Fabric.
단일 문의 읽기 전용 쿼리만 지원됩니다.

참고

Braze는 데이터에 대해 읽기 전용 쿼리만 실행하며 기본 테이블을 수정하지 않습니다. 쿼리 실행 중에 임시 객체가 생성될 수 있지만 유지되지는 않습니다.

새 SQL 편집기 동기화 만들기

다음 단계에 따라 먼저 소스를 만든 다음 SQL 편집기로 동기화를 만듭니다. CDI용 소스를 이미 설정했다면 3단계로 건너뛰어도 됩니다.

참고

이 단계에서는 Snowflake 소스를 예로 사용합니다. 다른 데이터 웨어하우스 소스의 설정 과정도 비슷하며, 데이터 웨어하우스 통합 설정하기 설명서의 2단계: Braze 대시보드에서 새 소스 만들기에서 확인할 수 있습니다.

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

CDI에서 Snowflake 소스를 만들기 전에 Braze가 사용하는 Snowflake 사용자가 쿼리하려는 데이터와 쿼리를 실행할 웨어하우스에 액세스할 수 있는지 확인하세요.

1.1단계: (선택 사항) 데이터베이스 및 스키마 만들기

필요한 경우 CDI 데이터 전용 데이터베이스와 스키마를 만듭니다.

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;

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

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

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;

사용 사례에 따라 여러 테이블이나 향후 생성될 테이블에 대한 액세스 권한을 부여할 수도 있습니다. 예를 들어 스키마에서 향후 생성될 모든 테이블에 대한 액세스 권한을 부여하려면 다음을 실행합니다.

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

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

Braze가 쿼리를 실행할 웨어하우스를 만듭니다.

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

참고

웨어하우스에는 자동 재개(auto-resume) 플래그가 켜져 있어야 합니다. 그렇지 않은 경우 쿼리 실행 시 Braze가 웨어하우스를 켤 수 있도록 웨어하우스에 대한 추가 OPERATE 권한을 Braze에 부여하세요.

1.4단계: Snowflake 사용자 만들기

Braze는 Workload Identity Federation 또는 RSA 키 페어를 사용하여 Snowflake에 인증합니다. 기존 RSA 키 페어 자격 증명은 계속 작동하므로 마이그레이션할 필요가 없습니다. 두 방법 중 하나를 따르세요. 이 사용자는 Braze에서 Snowflake 소스를 구성할 때 사용합니다.

workload identity federation
key pair

1.2단계와 1.3단계의 역할 및 웨어하우스 권한 부여를 사용합니다. Snowflake 자격 증명 양식에서 서비스 사용자를 만들고, 해당 명령문을 Snowflake 워크시트에서 실행합니다. 이 사용자는 TYPE = SERVICE이며 비밀번호와 RSA 키가 없습니다. Snowflake 계정에서 네트워크 정책을 사용하는 경우 1.5단계: Snowflake 네트워크 정책에서 Braze IP 허용하기(선택 사항)에 설명된 대로 Braze IP 주소를 허용하세요. 명령문의 역할과 실행 위치는 Workload Identity Federation용 Snowflake 구성하기를 참조하세요.

Braze용 사용자를 만들고 역할을 할당합니다.

CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

2단계: Braze 대시보드에서 새 소스 만들기

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

2.1단계: Snowflake 소스 추가하기

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

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

소스 이름을 정하고 Snowflake 자격 증명과 구성을 입력합니다.

참고

Snowflake 계정 로케이터 필드에는 Snowflake 계정 식별자를 입력합니다. 이 식별자는 일반적으로 xy12345.us-east-1.aws와 같은 형식입니다. 데이터베이스 이름이나 웨어하우스 이름과는 다릅니다.

2.3단계: 인증 완료하기

1.4단계에서 만든 사용자에 맞게 Workload Identity Federation 또는 Key pair를 선택합니다.

workload identity federation
key pair

계정 로케이터, 사용자 이름, 역할을 입력합니다. 명령문 복사가 표시되면 선택하고, Snowflake 워크시트에서 명령문을 실행한 다음 자격 증명 저장을 선택합니다. 명령문은 Workload Identity Federation용 Snowflake 구성하기를 참조하세요.

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

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

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

Braze로 돌아와 연결 테스트를 선택하여 소스 액세스를 확인한 다음 소스를 만듭니다.

3단계: 새 동기화 만들기 및 SQL 쿼리 작성하기

데이터 설정 > 클라우드 데이터 수집 > 동기화로 이동합니다.
데이터 동기화 생성을 선택합니다.
데이터 유형에서 원하는 동기화를 선택합니다.
2단계에서 만든 소스를 참조합니다.
SQL을 선택하고 웨어하우스에서 사용자 데이터를 반환하는 SQL 쿼리를 작성합니다. SQL 쿼리는 Braze에 동기화되는 데이터를 정의합니다. 쿼리 결과가 동기화의 스키마가 됩니다.

소스 탐색기를 사용하여 동기화할 수 있는 테이블과 뷰를 찾아보거나, AI SQL 생성기를 사용하여 SQL 쿼리 작성에 Braze Operator의 도움을 받을 수 있습니다.

참고

JOIN 절을 포함한 읽기 전용 쿼리만 지원됩니다. 자세한 내용은 SQL 제약 조건을 참조하세요.

4단계: 쿼리 미리 보기 및 유효성 검사하기

미리 보기 및 유효성 검사를 선택하여 쿼리를 실행합니다.

미리 보기는 다음과 같습니다.

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

유효성 검사를 통과하려면 SQL 쿼리가 다음 필수 열을 반환해야 합니다.

동기화 데이터 유형	필수 열
속성	- 사용자 식별자: `external_id`, `braze_id`, `alias_name` 및 `alias_label`, 이메일 또는 전화번호 중 하나. - `UPDATED_AT`. - 동기화할 추가 열(속성) 하나 이상.
사용자 삭제	- 사용자 식별자: `external_id`, `braze_id`, `alias_name` 및 `alias_label`, 이메일 또는 전화번호 중 하나. - `UPDATED_AT`.
Canvas 트리거	- 사용자 식별자: `external_id`, `braze_id`, `alias_name` 및 `alias_label`, 이메일 또는 전화번호 중 하나. - `UPDATED_AT`.
커스텀 이벤트	- 사용자 식별자: `external_id`, `braze_id`, `alias_name` 및 `alias_label`, 이메일 또는 전화번호 중 하나. - `UPDATED_AT`. - 이벤트 이름을 나타내는 `NAME`. - 이벤트 시간을 나타내는 `TIME`. 없는 경우 CDI는 `UPDATED_AT`을 대신 사용합니다.
구매 이벤트	- 사용자 식별자: `external_id`, `braze_id`, `alias_name` 및 `alias_label`, 이메일 또는 전화번호 중 하나. - `UPDATED_AT`. - `PRODUCT_ID`. - `CURRENCY`. - `PRICE`. - 구매 이벤트 시간을 나타내는 `TIME`. 없는 경우 CDI는 `UPDATED_AT`을 대신 사용합니다.
카탈로그	- 카탈로그 아이템 식별자를 나타내는 `ID`. - `UPDATED_AT`. - 동기화할 추가 열(카탈로그 필드) 하나 이상.
계정	- 계정 식별자를 나타내는 `ID`. - 계정 이름을 나타내는 `NAME`. - `UPDATED_AT`. - 동기화할 추가 열(계정 필드) 하나 이상.

필수 열 외의 추가 열은 각각 속성, Canvas 컨텍스트 속성, 이벤트 속성정보, 카탈로그 필드, 계정 필드로 동기화됩니다. 미리 보기 및 유효성 검사 오류와 해결 방법에 대한 유용한 팁은 유효성 검사 동작 및 문제 해결을 참조하세요.

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

유효성 검사에 성공하면 다음: 알림으로 계속 진행하여 동기화를 만듭니다.

중요

부정확한 SQL 구성은 데이터 포인트 과다 소비와 더 광범위한 운영상의 위험 등 의도하지 않은 결과로 이어질 수 있습니다. 쿼리 로직이 올바른지 확인하는 것은 사용자의 책임이며, 동기화를 활성화하기 전에 모든 결과를 신중하게 미리 확인해야 합니다.

SQL 제약 조건

`SELECT` 쿼리만 사용

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

사용할 수 있는 항목:

SELECT
WITH (CTE)
JOIN

사용할 수 없는 항목:

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

단일 문 사용

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

검증 동작

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

SQL 오류

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

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

컴파일 오류

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

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

연결 오류

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

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

쿼리 시간 초과

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

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

테이블 스키마 오류

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

식별자 열이 발견되지 않은 경우
UPDATED_AT이 누락된 경우
기타 필수 열이 누락된 경우

이 경우 성공적인 검증을 위해 미리보기가 계속 표시됩니다. 각 동기화 데이터 유형에 필요한 열에 대한 자세한 내용은 이전 섹션의 4단계를 참조하세요.

결과가 0행인 경우

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

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

`PAYLOAD` 지원(레거시)

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

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

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

다음과 같이 처리됩니다.

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

SQL 동기화 편집

기존 동기화를 편집할 때는 다음 사항에 유의하세요.

SQL을 변경하면 다시 유효성 검사를 받아야 합니다.
유효하지 않은 변경 사항은 저장할 수 없습니다.
유효한 변경 사항은 저장한 후에 적용됩니다.

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

문제 해결

이 섹션에서는 자주 발생하는 오류와 해결 방법을 안내합니다.

“미리보기를 사용할 수 없음”

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

오류 유형	해결 단계
“미리보기를 사용할 수 없음”	오류 배너에서 힌트를 확인하세요.
“소스에 연결할 수 없음”	구성된 사용자 이름, 계정 로케이터 및 인증 방법을 확인하세요. 키 쌍을 사용하는 경우 RSA 공개 키가 Snowflake 사용자에 등록되어 있는지 확인하세요. 워크로드 아이덴티티 페더레이션을 사용하는 경우 자격 증명 양식에 표시된 문을 실행했는지 확인하세요. 웨어하우스가 실행 중인지 확인하세요. 네트워크 액세스를 확인하세요.
“SQL 구문 오류”	SQL 구문을 확인하세요.
“오브젝트가 존재하지 않거나 권한이 없음”	역할에 테이블에 대한 `SELECT` 액세스 권한이 있는지 확인하세요. 데이터베이스 및 스키마 권한을 확인하세요. 테이블 이름에 오타가 없는지 확인하세요.

“식별자 열 필수”

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

“`UPDATED_AT` 열 누락”

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

“열을 더 추가하세요… 동기화할 속성/카탈로그 필드/계정 필드가 없습니다”

식별자와 UPDATED_AT 외에 열을 하나 이상 추가하세요.

“쿼리 실행 시간 초과”

쿼리를 최적화하거나 더 큰 웨어하우스를 사용하세요.

New Stuff!