> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MotherDuck

> MotherDuck에서 OneSignal로 Custom Event를 동기화하여 사용자 행동을 기반으로 자동화된 Journey 및 개인화된 메시징 캠페인을 트리거하세요.

export const PLATFORM_0 = "MotherDuck"

export const DATA_TYPE_0 = "table columns"

export const COLUMN_HEADER_0 = "MotherDuck Column"

export const PROPERTIES_DESCRIPTION_0 = "JSON object with event metadata"

## 개요

OneSignal + MotherDuck 통합은 MotherDuck 데이터베이스에서 OneSignal로 Custom Event를 자동으로 동기화하여 사용자 행동을 기반으로 자동화된 메시징 캠페인 및 Journey를 트리거할 수 있게 합니다.

MotherDuck는 SQL의 단순성으로 빠른 OLAP(Online Analytical Processing) 기능을 제공하는 클라우드 기반 DuckDB 서비스입니다.

***

## 요구 사항

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### MotherDuck

* 데이터베이스 액세스 권한이 있는 **MotherDuck 계정**
* 인증을 위한 **Service token**
* 이벤트 데이터가 포함된 **데이터베이스**
* 구조화된 이벤트 정보가 있는 **테이블 또는 뷰**

***

## 설정

<Steps>
  <Step title="MotherDuck Service token 생성">
    OneSignal이 MotherDuck에 연결할 수 있도록 액세스 토큰을 생성하세요:

    1. `app.motherduck.com`에서 MotherDuck Web UI에 로그인합니다
    2. 왼쪽 상단의 프로필을 클릭합니다
    3. **Settings** > **General** > **Access Tokens**로 이동합니다
    4. **Create Token**을 클릭합니다
    5. 만료 날짜를 설정하거나 무제한으로 둡니다
    6. 생성된 Service token을 복사합니다
  </Step>

  <Step title="이벤트 데이터 준비">
    MotherDuck 데이터베이스에 올바르게 구조화된 이벤트 테이블이 포함되어 있는지 확인하세요:

    ```sql theme={null}
    -- Example event table structure
    CREATE TABLE user_events (
        event_name VARCHAR,
        user_id VARCHAR,
        event_timestamp TIMESTAMP,
        event_properties JSON,
        session_id VARCHAR
    );
    ```
  </Step>

  <Step title="OneSignal에 연결">
    OneSignal에서 **Data > Integrations**으로 이동하여 **Add Integration**을 클릭합니다.

    **MotherDuck**를 선택하고 다음을 제공하세요:

    * **Service Token:** 1단계의 토큰
    * **Database Name:** MotherDuck 데이터베이스 이름
    * **Connection String:** `md:your_database_name`
  </Step>

  <Step title="데이터 동기화 구성">
    테이블을 선택하거나 사용자 지정 SQL 쿼리를 작성하여 동기화할 이벤트 데이터를 정의하세요:

    ```sql theme={null}
    SELECT
        event_name,
        user_id,
        event_timestamp,
        event_properties
    FROM user_events
    WHERE event_timestamp >= CURRENT_DATE - INTERVAL 7 DAYS
    ```
  </Step>
</Steps>

***

### 이벤트 데이터 매핑

{PLATFORM_0} {DATA_TYPE_0}를 OneSignal의 사용자 지정 이벤트 형식에 매핑합니다:

| OneSignal 필드  | {COLUMN_HEADER_0} | 설명                         | 필수  |
| ------------- | ----------------- | -------------------------- | --- |
| `name`        | `event_name`      | 이벤트 식별자                    | Yes |
| `external_id` | `user_id`         | 사용자 식별자                    | Yes |
| `timestamp`   | `event_timestamp` | 이벤트가 발생한 시간                | No  |
| `properties`  | `event_data`      | {PROPERTIES_DESCRIPTION_0} | No  |

### 예제 이벤트 쿼리

```sql theme={null}
-- Optimized event query for OneSignal sync
SELECT
    event_name,
    user_id,
    event_timestamp,
    {
        'source': 'motherduck',
        'session_id': session_id,
        'device_type': device_type,
        'value': event_value
    }::JSON as event_properties
FROM analytics.user_events
WHERE event_timestamp >= CURRENT_TIMESTAMP - INTERVAL 1 DAY
ORDER BY event_timestamp DESC
```

***

## 처리 모드

### Table 모드

MotherDuck 데이터베이스에서 직접 전체 테이블을 동기화합니다. OneSignal이 자동으로 열을 이벤트 필드에 매핑합니다.

### SQL Query 모드

사용자 지정 DuckDB SQL 쿼리를 작성하여 이벤트 데이터를 변환하고 필터링합니다:

```sql theme={null}
-- Advanced event aggregation
SELECT
    'daily_summary' as event_name,
    user_id,
    DATE_TRUNC('day', event_timestamp) as event_timestamp,
    {
        'total_events': COUNT(*),
        'unique_sessions': COUNT(DISTINCT session_id),
        'last_activity': MAX(event_timestamp)
    }::JSON as event_properties
FROM user_events
WHERE event_timestamp >= CURRENT_DATE - INTERVAL 7 DAYS
GROUP BY user_id, DATE_TRUNC('day', event_timestamp)
```

***

## 제한 사항

* 쿼리 복잡성이 동기화 성능에 영향을 미칩니다
* 대규모 결과 세트는 동기화 속도에 영향을 줄 수 있습니다
* JSON 파싱에는 적절한 열 타이핑이 필요합니다

***

## FAQ

### MotherDuck에서 쿼리 성능을 최적화하려면 어떻게 하나요?

필요한 열만 선택하고 쿼리 초반에 필터를 적용하여 DuckDB의 컬럼형 스토리지 이점을 활용하세요.

### 여러 MotherDuck 데이터베이스에서 동기화할 수 있나요?

예, 계정의 각 MotherDuck 데이터베이스에 대해 별도의 통합을 생성할 수 있습니다.

***