> ## 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.

# ClickHouse

> ClickHouse에서 OneSignal로 사용자 지정 이벤트를 동기화하여 사용자 행동을 기반으로 자동화된 Journeys 및 개인화된 메시징 캠페인을 트리거합니다.

export const PLATFORM_0 = "ClickHouse"

export const DATA_TYPE_0 = "이벤트 테이블 열"

export const COLUMN_HEADER_0 = "ClickHouse 열"

export const PROPERTIES_DESCRIPTION_0 = "JSON 열 또는 여러 열"

## 개요

OneSignal + ClickHouse 통합을 사용하면 ClickHouse 분석 데이터베이스에서 OneSignal로 사용자 지정 이벤트를 자동으로 동기화할 수 있습니다. 이를 통해 고성능 열형 데이터베이스에 저장된 사용자 행동 데이터를 기반으로 자동화된 Journeys 및 개인화된 메시징 캠페인을 트리거할 수 있습니다.

***

## 요구 사항

* 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)

### ClickHouse

* **ClickHouse 서버** (자체 호스팅 또는 클라우드)
* 이벤트 테이블에 대한 읽기 액세스 권한이 있는 **데이터베이스 자격 증명**
* 적절한 스키마로 행동 데이터를 포함하는 **이벤트 데이터 테이블**

***

## 설정

<Steps>
  <Step title="OneSignal용 ClickHouse 사용자 만들기">
    이벤트 테이블에 대한 읽기 전용 액세스 권한이 있는 OneSignal용 전용 사용자 계정을 만드세요:

    ```sql theme={null}
    CREATE USER onesignal_reader IDENTIFIED BY 'strong_password';
    GRANT SELECT ON event_database.* TO onesignal_reader;
    ```
  </Step>

  <Step title="네트워크 액세스 구성">
    OneSignal이 ClickHouse 인스턴스에 연결할 수 있는지 확인하세요:

    * **자체 호스팅**: OneSignal의 IP 주소에서 연결 허용
    * **ClickHouse Cloud**: 허용 목록에 OneSignal IP 추가
    * **포트**: 기본 ClickHouse 포트는 8123(HTTP) 또는 9000(네이티브)입니다
  </Step>

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

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

    * **호스트**: ClickHouse 서버 호스트 이름 또는 IP
    * **포트**: ClickHouse 포트(기본값: HTTP의 경우 8123, 네이티브의 경우 9000)
    * **데이터베이스**: 이벤트 테이블을 포함하는 데이터베이스 이름
    * **사용자 이름**: `onesignal_reader`(또는 선택한 사용자 이름)
    * **비밀번호**: ClickHouse 사용자의 비밀번호
    * **프로토콜**: HTTP 또는 Native(단순성을 위해 HTTP 권장)
  </Step>

  <Step title="이벤트 데이터 소스 구성">
    이벤트 데이터를 포함하는 ClickHouse 테이블을 지정하세요:

    * **테이블**: 이벤트 레코드를 포함하는 테이블 이름(예: `user_events`)
    * **이벤트 쿼리**: 이벤트 데이터를 필터링하거나 변환하는 선택적 SQL 쿼리

    이벤트 테이블에는 다음 열이 포함되어야 합니다:

    * 이벤트 이름/유형 (String)
    * 사용자 식별자 (String)
    * 이벤트 타임스탬프 (DateTime)
    * 추가 이벤트 속성 (JSON 또는 개별 열)
  </Step>

  <Step title="연결 테스트">
    **Test Connection**을 클릭하여 OneSignal이 ClickHouse 데이터베이스에 액세스하고 이벤트 데이터를 읽을 수 있는지 확인하세요.
  </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 쿼리

OneSignal에 동기화하기 전에 사용자 지정 SQL을 사용하여 이벤트 데이터를 필터링하거나 변환하세요:

```sql theme={null}
SELECT
  event_name,
  user_id,
  toDateTime(event_timestamp) as timestamp,
  toJSONString(
    map(
      'product_id', product_id,
      'purchase_amount', purchase_amount,
      'category', category
    )
  ) as payload
FROM user_events
WHERE event_timestamp >= now() - INTERVAL 7 DAY
  AND event_name IN ('purchase', 'signup', 'upgrade')
ORDER BY event_timestamp DESC
```

### 성능 최적화

ClickHouse는 분석 쿼리에 최적화되어 있습니다. 다음을 고려하세요:

* **파티셔닝**: 이벤트 타임스탬프에 날짜 기반 파티셔닝 사용
* **인덱싱**: user\_id 및 event\_name에 적절한 인덱스 생성
* **Materialized Views**: 더 빠른 쿼리를 위해 이벤트 데이터를 사전 집계

<Warning>
  ClickHouse는 추가 전용 워크로드에 최적화되어 있습니다. 최상의 성능을 위해 이벤트 데이터가 이 패턴을 따르는지 확인하세요.
</Warning>

***

## FAQ

### OneSignal이 ClickHouse에서 이벤트를 얼마나 자주 동기화하나요?

OneSignal은 구성된 일정에 따라 이벤트 데이터를 동기화하며 최소 간격은 15분입니다.

### 여러 ClickHouse 테이블에서 이벤트를 동기화할 수 있나요?

예, 다른 테이블에 대해 여러 통합을 만들거나 UNION 쿼리를 사용하여 여러 테이블의 데이터를 결합할 수 있습니다.