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

# Materialize

> 将 Materialize 的自定义事件同步到 OneSignal，基于实时用户行为触发自动化 Journey 和个性化消息传递活动。

export const PLATFORM_0 = "Materialize"

export const DATA_TYPE_0 = "view or table columns"

export const COLUMN_HEADER_0 = "Materialize Column"

export const PROPERTIES_DESCRIPTION_0 = "JSON object with event metadata"

## 概览

OneSignal + Materialize 集成可以自动将您的 Materialize 流式数据库中的自定义事件同步到 OneSignal，以基于实时用户行为触发自动化消息活动和 Journey。

Materialize 是一个与 PostgreSQL 兼容的流式数据库，维护您数据的增量更新视图，实现实时分析和事件处理。

***

## 要求

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

### Materialize 要求

* 具有控制台访问权限的 **Materialize 账户**
* 用于外部工具身份验证的 **应用程序密码**
* 包含事件数据的 **物化视图** 或表
* 您的 Materialize 数据库中可访问的 **事件数据**

***

## 设置

<Steps>
  <Step title="获取 Materialize 连接详细信息">
    登录 Materialize 控制台并导航到**连接**页面查找您的连接详情。
  </Step>

  <Step title="创建应用密码">
    在 Materialize 控制台中，为 OneSignal 创建一个新的**应用密码**用于身份验证。
  </Step>

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

    选择 **Materialize** 并提供：

    * **主机：** 您的 Materialize 主机名（在 Materialize 控制台连接页面的**外部工具**下找到）
    * **用户名：** 您的电子邮件地址（用于登录 Materialize）
    * **密码：** 在步骤 2 中创建的应用密码
    * **数据库：** 数据库名称（可选，默认为 `materialize`）
  </Step>

  <Step title="测试连接">
    点击**测试**验证连接是否正常工作。
  </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}
-- Real-time materialized view for recent events
CREATE MATERIALIZED VIEW analytics.recent_user_events AS
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_properties,
    session_id,
    device_type
FROM raw_events.stream
WHERE event_timestamp >= NOW() - INTERVAL '1 day';
```

***

## 处理模式

### 物化视图（推荐）

通过从随着新数据到达而自动更新的物化视图同步，利用 Materialize 的实时处理功能：

```sql theme={null}
-- High-value events materialized view
CREATE MATERIALIZED VIEW analytics.high_value_events AS
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_properties || jsonb_build_object(
        'source', 'materialize',
        'value_tier', 'high'
    ) as event_properties
FROM raw_events.stream
WHERE (event_properties->>'value')::numeric > 100;
```

### SQL 查询模式

编写自定义的 PostgreSQL 兼容查询来转换您的事件数据：

```sql theme={null}
-- Real-time user activity summary
SELECT
    'activity_summary' as event_name,
    user_id,
    NOW() as event_timestamp,
    jsonb_build_object(
        'events_last_hour', COUNT(*),
        'unique_sessions', COUNT(DISTINCT session_id),
        'total_value', SUM((event_properties->>'value')::numeric),
        'last_seen', MAX(event_timestamp)
    ) as event_properties
FROM analytics.recent_user_events
WHERE event_timestamp >= NOW() - INTERVAL '1 hour'
GROUP BY user_id
HAVING COUNT(*) >= 5;
```

### 实时流处理

```sql theme={null}
-- Progressive profiling view
CREATE MATERIALIZED VIEW analytics.user_progression AS
SELECT
    user_id,
    COUNT(*) as total_events,
    COUNT(DISTINCT event_name) as unique_event_types,
    MAX(event_timestamp) as last_activity,
    CASE
        WHEN COUNT(*) >= 50 THEN 'power_user'
        WHEN COUNT(*) >= 20 THEN 'active_user'
        WHEN COUNT(*) >= 5 THEN 'engaged_user'
        ELSE 'new_user'
    END as user_segment
FROM raw_events.stream
GROUP BY user_id;
```

***

## 限制

* Materialize 仅支持基本同步引擎
* 实时查询可能消耗更多计算资源
* 大型数据集的复杂连接应该被优化
* 物化视图需要持续的集群资源

***

## 常见问题

### 如何优化 Materialize 中的实时性能？

在经常查询的列上使用索引，并考虑按时间范围对大型事件数据集进行分区以获得更好的性能。

### 我可以同时从表和物化视图同步数据吗？

是的，OneSignal 可以从 Materialize 中的静态表和实时物化视图中读取数据。

### 实时同步是如何工作的？

Materialize 维护增量更新的视图，因此 OneSignal 将始终读取您数据的最新状态，而无需额外的处理开销。

***