> ## 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，基于用户行为触发自动化 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，以基于用户行为触发自动化消息活动和 Journey。

MotherDuck 是一个 DuckDB 云服务，提供快速的 OLAP（在线分析处理）功能，具有 SQL 的简单性。

***

## 要求

* 访问自定义事件（目前处于测试阶段）
* [升级账户计划](https://onesignal.com/pricing)（免费应用不可用）。

### MotherDuck 要求

* 具有数据库访问权限的 **MotherDuck 账户**
* 用于身份验证的 **服务令牌**
* 包含事件数据的 **数据库**
* 具有结构化事件信息的 **表或视图**

***

## 设置

<Steps>
  <Step title="创建 MotherDuck 服务令牌">
    生成一个供 OneSignal 连接到 MotherDuck 的访问令牌：

    1. 在 `app.motherduck.com` 登录 MotherDuck Web UI
    2. 点击左上角的个人资料
    3. 导航到 **设置** > **常规** > **访问令牌**
    4. 点击 **创建令牌**
    5. 设置过期日期（或保持无限制）
    6. 复制生成的服务令牌
  </Step>

  <Step title="准备您的事件数据">
    确保您的 MotherDuck 数据库包含正确结构的事件表：

    ```sql theme={null}
    -- 示例事件表结构
    CREATE TABLE user_events (
        event_name VARCHAR,
        user_id VARCHAR,
        event_timestamp TIMESTAMP,
        event_properties JSON,
        session_id VARCHAR
    );
    ```
  </Step>

  <Step title="连接到 OneSignal">
    在 OneSignal 中，前往 **数据 > 集成**，然后点击 **添加集成**。

    选择 **MotherDuck** 并提供：

    * **服务令牌：** 步骤 1 中的令牌
    * **数据库名称：** 您的 MotherDuck 数据库名称
    * **连接字符串：** `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`      | 事件标识符                      | 是  |
| `external_id` | `user_id`         | 用户标识符                      | 是  |
| `timestamp`   | `event_timestamp` | 事件发生时间                     | 否  |
| `properties`  | `event_data`      | {PROPERTIES_DESCRIPTION_0} | 否  |

### 事件查询示例

```sql theme={null}
-- 针对 OneSignal 同步优化的事件查询
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
```

***

## 处理模式

### 表模式

直接从您的 MotherDuck 数据库同步整个表。OneSignal 将自动将列映射到事件字段。

### SQL 查询模式

编写自定义 DuckDB SQL 查询来转换和过滤您的事件数据：

```sql theme={null}
-- 高级事件聚合
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 解析需要正确的列类型

***

## 常见问题

### 如何优化 MotherDuck 中的查询性能？

通过仅选择所需列并在查询中提前应用过滤器来利用 DuckDB 的列式存储优势。

### 我可以从多个 MotherDuck 数据库同步吗？

是的，您可以为账户中的每个 MotherDuck 数据库创建单独的集成。

***