쿼리 빌더 SQL 변수

쿼리 빌더에서 SQL 변수를 사용하여 쿼리를 재사용하고 코드에 데이터를 하드코딩하지 않는 방법을 알아보세요.

SQL 변수를 사용하는 이유

SQL 변수를 사용하면 다음과 같은 이점이 있습니다:

• 보고서를 생성할 때 Campaign ID를 직접 붙여넣는 대신, Campaign 변수를 만들어 목록에서 선택할 수 있으므로 시간을 절약할 수 있습니다.
• 변수를 추가하면 향후 약간 다른 사용 사례(예: 다른 커스텀 이벤트)에 대해 보고서를 재사용할 수 있습니다.
• 각 보고서에 필요한 편집량을 줄여 SQL 편집 시 사용자 오류를 줄일 수 있습니다. SQL에 익숙한 팀원이 보고서를 만들면 기술적 배경이 적은 팀원도 사용할 수 있습니다.

변수 사용하기

1단계: 변수 추가

쿼리에 변수를 추가하려면 다음 구문을 사용합니다:

1
{{variable_type.${custom_label}}}

다음을 교체합니다:

다음 예시에서는 한 달의 첫째 날과 마지막 날 사이의 총 사용자 수를 Campaign에 대해 쿼리합니다. 각 변수에는 다음 단계에서 값이 할당됩니다.

1
2
3
4
5
SELECT COUNT(*) AS total_users
FROM USERS_CAMPAIGNS_REVENUE_SHARED
WHERE campaign_id = '{{campaign.${Campaign}}}'
  AND TIME > '{{start_date.${Month First Day}}}'
  AND TIME < '{{end_date.${Month Last Day}}}';

2단계: 값 할당

기본적으로 변수 탭은 쿼리 빌더에 표시되지 않습니다. 쿼리에 첫 번째 변수를 추가한 후에만 나타납니다. 거기에서 값을 할당할 수 있습니다. 선택할 수 있는 구체적인 값은 해당 변수의 유형에 따라 달라집니다.

다음 예시에서는 “Summer Feature Launch” Campaign이 값으로 할당되며, 2025년 6월의 첫째 날과 마지막 날도 함께 지정됩니다.

일반 변수 유형

숫자

number는 문자열이 아닌 다른 변수와 조합하여 사용할 수 있습니다. 5.5와 같은 소수를 포함하여 양수 또는 음수를 허용합니다.

• 사용법

1
some_number_column < {{number.${custom_label}}}

문자열

보고서 실행 간에 반복되는 문자열 값을 변경하는 데 사용합니다. SQL에서 값을 여러 번 하드코딩하지 않으려면 이 변수를 사용하세요.

• 사용법

1
'{{string.${add a string here.}}}'

목록

옵션 목록에서 선택하는 데 사용합니다.

• 하나 선택
• 여러 개 선택

1
{{options.${metrics} | is_radio_button: 'true' | options: '[{"label": "test", "value": "test_value"}, {"label": "test2", "value": "test_value2"}]'}}

1
{{options.${metrics} | is_multi_select: 'true' | options: '[{"label": "test", "value": "test_value"}, {"label": "test2", "value": "test_value2"}]'}}

라디오 버튼

변수 탭에서 선택 드롭다운 대신 라디오 버튼으로 옵션을 표시하는 데 사용합니다. 단독으로 사용할 수 없으며—목록과 함께 사용해야 합니다.

• 사용법

1
is_radio_button: 'true'

다중 선택

선택 드롭다운에서 단일 선택 또는 다중 선택을 허용할지 여부를 설정합니다. 단독으로 사용할 수 없으며—목록과 함께 사용해야 합니다.

• 사용법

1
is_multi_select: 'true'

옵션

레이블과 값 형태로 선택 가능한 옵션 목록을 제공하는 데 사용합니다. 레이블은 표시되는 내용이고, 값은 옵션이 선택될 때 변수가 대체되는 내용입니다. 단독으로 사용할 수 없으며—목록과 함께 사용해야 합니다.

• 사용법

1
options: '[{"label": "test", "value": "test_value"}, {"label": "test2", "value": "test_value2"}]'

Braze 전용 변수 유형

날짜 범위

날짜를 선택할 수 있는 캘린더를 표시하는 데 사용합니다. start_date와 end_date를 UTC 기준 지정된 날짜의 Unix 타임스탬프(초 단위)로 교체합니다(예: 1696517353). 선택적으로 start_date 또는 end_date만 설정하여 캘린더에 단일 날짜만 표시할 수도 있습니다. start_date와 end_date의 레이블이 일치하지 않으면 날짜 범위가 아닌 두 개의 별도 날짜로 처리됩니다.

• 사용법

1
time > {{start_date.${custom_label}}} AND time < {{end_date.${custom_label}}}

날짜 범위를 다음 옵션 중 하나로 설정할 수 있습니다. start_date와 end_date가 모두 사용되고 동일한 레이블을 공유하면 모든 옵션이 표시됩니다. 그렇지 않고 하나만 사용되면 지정된 옵션만 표시됩니다.

Liquid는 지정된 날짜 범위 내에서 캘린더를 표시하는 데 사용됩니다:

Campaigns

• 단일 campaign
• 다중 campaign
• 캠페인 배리언트

1
campaign_id = '{{campaign.${custom_label}}}'

1
campaign_id IN ({{campaigns.${custom_label}}})

1
message_variation_api_id IN ({{campaign_variants.${custom_label}}})

Canvases

• 단일 canvas
• 다중 canvas
• 캔버스 배리언트
• 단일 캔버스 단계
• 다중 캔버스 단계

1
canvas_id = '{{canvas.${custom_label}}}'

1
canvas_id IN ({{canvases.${custom_label}}})

1
canvas_variation_api_id IN ({{canvas_variants.${custom_label}}})

1
canvas_step_api_id = '{{canvas_step.${custom_label}}}'

1
canvas_step_api_id IN ({{canvas_steps.${custom_label}}})

제품

products는 Braze 대시보드에서 하나 이상의 제품을 선택하는 데 사용합니다.

• 사용법
• 예시

1
({{products.${custom_label}}})

1
2
3
SELECT product_name
FROM FULL_GAME_AND_DLC
WHERE product_id IN ({{products.${Games with DLC}}});

커스텀 이벤트

목록에서 하나 이상의 커스텀 이벤트 또는 커스텀 이벤트 등록정보를 선택합니다.

• 이벤트
• 등록정보

1
'{{custom_events.${custom_label}}}'

1
2
3
SELECT event_name
FROM CUSTOM_EVENTS_TABLE
WHERE event_name IN ({{custom_events.${Purchased Game}}});

1
name = '{{custom_event_properties.${property names)}}}'

워크스페이스

workspace는 Braze 대시보드에서 단일 워크스페이스를 선택하는 데 사용합니다.

• 사용법

1
workspace_id = '{{workspace.${app_group_id}}}'

카탈로그

목록에서 하나 이상의 카탈로그 또는 카탈로그 필드를 선택합니다.

• 카탈로그
• 카탈로그 필드

1
catalog_id = '{{catalogs.${catalog}}}'

1
field_name = '{{catalog_fields.${custom_label}}}'

Segments

분석 추적이 활성화된 Segment를 선택하는 데 사용합니다. 이 열이 사용 가능한 테이블의 user_segment_membership_ids 열에 저장된 ID에 해당하는 Segment 분석 ID로 설정합니다.

• 사용법

1
{{segments.${analytics_segments}}}

태그

Campaigns 및 Canvases의 태그를 선택하는 데 사용합니다. 선택한 태그와 연결된 작은따옴표로 구분된 쉼표 구분 BSON ID를 가진 Campaigns 및 Canvases로 설정됩니다.

• 사용법

1
{{tags.${some tags}}}

변수 메타데이터

메타데이터는 변수 레이블 뒤에 파이프( | ) 문자를 추가하여 변수에 첨부할 수 있으며, 이를 통해 변수의 동작을 변경할 수 있습니다. 메타데이터의 순서는 중요하지 않으며 원하는 수만큼 추가할 수 있습니다. 또한 특정 변수에만 해당하는 특수 메타데이터를 제외하고 모든 유형의 메타데이터를 모든 변수에 사용할 수 있습니다(해당하는 경우 표시됩니다). 모든 메타데이터의 사용은 선택 사항이며 변수의 기본 동작을 변경하는 데 사용됩니다.

• 사용법

1
{{string.${my var}| is_required: 'false' | description: 'My optional string var'}}

부울

변수의 값이 채워져 있는지 여부를 확인하는 데 사용합니다. 변수의 값이 채워지지 않은 경우 조건을 단축하려는 선택적 변수에 유용합니다. 다른 변수의 값에 따라 true 또는 false로 설정할 수 있습니다.

• 사용법

1
{{string.${type_name_has_no_value} | visible: 'false'}} or {{string.${type_name_has_value} | visible: 'false'}}

type과 name은 참조되는 변수를 나타냅니다. 예를 들어, 다음 선택적 변수를 단축하려면: {{campaigns.${messaging}}:

1
{{string.${campaigns_messaging_has_no_value}  | visible: 'false'}} OR campaign_id IN ({{campaigns.${messaging} | is_required: 'false'}})

표시 여부

변수가 표시되는지 여부를 설정합니다. 모든 변수는 기본적으로 변수 탭에 표시되며, 여기에서 값을 입력할 수 있습니다.

다른 변수에 값이 있는지 여부 등 다른 변수에 의존하는 값을 가진 특수 변수가 여러 개 있습니다. 이러한 특수 변수는 변수 탭에 표시되지 않도록 비표시로 설정됩니다.

• 사용법

1
visible: 'false'

필수

변수가 기본적으로 필수인지 여부를 설정합니다. 변수의 빈 값은 일반적으로 잘못된 쿼리로 이어집니다.

• 사용법

1
required: 'false'

순서

변수 탭에서 변수의 위치를 선택하는 데 사용합니다.

• 사용법

1
order: '1'

따옴표 포함

• 작은따옴표
• 큰따옴표

1
include_quotes: 'true'

1
include_double_quotes: 'true'

입력 안내 텍스트

변수의 입력 필드에 표시되는 입력 안내 텍스트를 지정하는 데 사용합니다.

• 사용법

1
placeholder: 'enter some value'

설명

변수의 입력 필드 아래에 표시되는 설명 텍스트를 지정하는 데 사용합니다.

• 사용법

1
description: 'some description'

기본값

값이 지정되지 않은 경우 변수의 기본값을 지정하는 데 사용합니다.

• 사용법

1
default_value: '5'

레이블 숨기기

변수의 레이블을 숨기는 데 사용합니다.

• 사용법

1
hide_label: 'true'