Title: ByteHouse
Locale: zh
URL: https://sensorswave.cn/docs/data-center/pipeline/destinations/bytehouse/
Description: 配置 ByteHouse 云数仓数据流，将事件数据和用户数据定期同步到火山引擎 ByteHouse
ByteHouse 连接器将 SensorsWave 中的事件数据和用户数据定期批量同步到您的 ByteHouse 云数仓版，帮助数据团队进行深度分析，并与其他业务数据进行联合查询。

> **支持版本**：目前仅支持 **火山引擎 ByteHouse 云数仓版**，暂不支持企业版与私有部署版。

典型使用场景：

- 将用户行为事件同步到 ByteHouse，与订单、CRM 数据进行 JOIN 分析
- 将用户画像数据导出，结合 BI 工具构建分析报表
- 保留 SensorsWave 中的历史事件数据，满足合规或长期分析需求

ByteHouse 连接器支持两种导出类型：

- **事件数据导出**：将用户行为事件增量同步到 `sensorswave_events` 表（默认，可在创建时自定义）
- **用户数据导出**：将用户画像属性增量同步到 `sensorswave_users` 表（默认，可在创建时自定义）

每种导出类型需要分别创建一条数据流。

SensorsWave 使用 TOS（火山引擎对象存储）作为 staging：增量数据先上传到您的 TOS Bucket，再由 ByteHouse 通过 `CnchS3` 表函数读取并加载到目标表。因此除 ByteHouse 本身，您还需要准备一个 TOS Bucket 并授予对应权限。

## 前提条件

在 SensorsWave 中创建数据流之前，需要在您的火山引擎账号下完成以下准备工作。建议为 SensorsWave 创建专用的 Database、Virtual Warehouse、Role 和 User，避免权限过大带来安全风险。

以下步骤使用如下对象名称作为示例，实际使用时请按客户规范调整：

| 对象 | 示例名称 | 说明 |
|------|---------|------|
| Database | `sensorswave` | 接收 SensorsWave 同步数据的目标库 |
| Virtual Warehouse | `sensorswave_vw` | 数据流执行所用的计算资源 |
| Role | `sensorswave_role` | 承载数据流所需权限的角色 |
| User | `sensorswave_user` | 数据流使用的账号 |
| TOS Bucket | `sensorswave` | 作为 staging 的对象存储桶 |

### 第 1 步：在火山引擎控制台配置 ByteHouse 基础对象

以下操作全部在 **火山引擎 → ByteHouse 控制台** 完成，无需编写 SQL。

1. **创建 Database**：在「数据库管理 → 新建数据库」创建 `sensorswave`。
2. **创建 Virtual Warehouse**：在「计算组管理 → 新建计算组」创建 `sensorswave_vw`，规格按业务数据量选择。
3. **创建 Role**：在「权限管理 → 角色 → 创建角色」创建 `sensorswave_role`。
4. **为 Role 授权**：在角色详情页为 `sensorswave_role` 在 `sensorswave` 数据库上授予以下权限：

   - `CREATE TABLE`
   - `DROP TABLE`
   - `INSERT`
   - `ALTER`
   - `SELECT`（可选）

5. **创建 User**：在「权限管理 → 用户 → 创建用户」创建 `sensorswave_user`，按以下要点配置：

   - **计算组使用权限**：勾选上一步创建的 `sensorswave_vw`，授予 User 使用该计算组运行 SQL 的权限（此权限在创建用户时配置，而非通过 Role 授予）。
   - **认证方式**（二选一）：
     - 账号密码认证：设置强密码，在数据流配置中填写 `Username` 和 `Password`。
     - IAM 认证：创建完成后生成 **API Key**，在数据流配置中填写 `API Key`。

6. **将 Role 授予 User**：用户创建完成后，在「权限管理 → 角色」进入 `sensorswave_role`，通过「授予用户」将 `sensorswave_user` 添加为该角色的成员。

### 第 2 步：补充授权 S3 与 CREATE TEMPORARY TABLE

`S3`（Source 类权限）与 `CREATE TEMPORARY TABLE`（会话级临时表）在 ByteHouse 授权模型中不归属任何 Database，火山引擎控制台未开放配置入口，需要通过 SQL 授权。

使用 **具备管理员权限的账号** 在 ByteHouse 管理后台的 SQL 控制台，或通过 [bytehouse-cli](https://www.volcengine.com/docs/6517/102213?lang=zh) 登录后执行：

```sql
GRANT S3, CREATE TEMPORARY TABLE ON *.* TO sensorswave_role;
```

### 第 3 步：准备 TOS Bucket 与 Access Key

SensorsWave 使用 TOS 作为 staging 对象存储，供 ByteHouse 通过 `CnchS3` 读取。请在火山引擎 TOS 控制台完成：

1. **创建 Bucket**：建议在与 ByteHouse 实例相同的区域创建 TOS Bucket（例如 `cn-beijing`），避免跨区域读写带来的额外延迟与费用。
2. **生成 Access Key**：在「访问控制 → 访问密钥」创建用于 SensorsWave 的 AK/SK。

授予该 AK/SK 以下最小权限（仅限上述 Bucket）：

- `tos:PutObject`
- `tos:GetObject`
- `tos:DeleteObject`
- `tos:ListBucket`

## 创建数据流

完成 ByteHouse 与 TOS 侧的准备工作后，在 SensorsWave 中创建数据流。

1. 进入**数据中心 → 数据流**，点击**新建数据流**按钮。
2. 在弹出的对话框中，选择**导出数据流**，点击**下一步**。
3. 选择**数据源类型**：
   - **事件数据**：同步用户行为事件
   - **用户数据**：同步用户信息与属性
4. 选择**连接器**为 **ByteHouse**。
5. 填写 ByteHouse 与 TOS 连接配置（详见下方「配置参考」）。
6. 点击**测试连接**，等待连接验证通过。
7. 配置**执行频率**（详见下方「执行频率」）。
8. 如需仅同步特定事件，在**高级选项**中配置事件过滤（仅事件数据导出支持）。
9. 点击**保存**，数据流将立即启动，并自动在 ByteHouse 中创建目标表。

## 配置参考

### 连接配置

**ByteHouse 配置**：

| 字段 | 必填 | 说明 | 示例 |
|------|------|------|------|
| `Host` | 是 | ByteHouse 公网访问地址 | `tenant-2100000000-cn-beijing-public.bytehouse.volces.com` |
| `Port` | 是 | ByteHouse **TCP 连接端口**（非 HTTP 端口），默认 `19000` | `19000` |
| `Database` | 是 | 目标数据库名称 | `sensorswave` |
| `Virtual Warehouse` | 否 | 计算组名称；留空则使用 User 在火山引擎控制台绑定的默认计算组 | `sensorswave_vw` |
| `认证方式` | 是 | `IAM (API Key)` 或 `账号密码` | `账号密码` |
| `Account ID` | 是 | 火山引擎账号 ID（两种认证方式都需要） | `2100000000` |
| `Username` | 仅账号密码 | ByteHouse 用户名 | `sensorswave_user` |
| `Password` | 仅账号密码 | ByteHouse 密码 | — |
| `API Key` | 仅 IAM | IAM 用户的 API Key | — |
| `Table` | 是 | 目标表名，可自定义；默认 `sensorswave_events`（事件）或 `sensorswave_users`（用户），保存后系统自动创建 | `sensorswave_events` |

**TOS 配置**：

| 字段 | 必填 | 说明 | 示例 |
|------|------|------|------|
| `Endpoint` | 是 | TOS 公网 Endpoint（TOS 原生格式，非 S3 兼容格式） | `tos-cn-beijing.volces.com` |
| `Region` | 是 | TOS Region ID，取值参考[火山引擎 Region 及 Endpoint 对照表](https://www.volcengine.com/docs/6349/107356?lang=zh) | `cn-beijing` |
| `Bucket` | 是 | TOS Bucket 名称 | `sensorswave` |
| `Access Key` | 是 | TOS AK | `AKLT...` |
| `Secret Key` | 是 | TOS SK | — |

> **注意**：`Password`、`API Key`、`Secret Key` 均为敏感凭证，SensorsWave 会进行加密存储，保存后不再回显。编辑已有数据流时，对应字段显示「已配置，留空则保持不变」，如无需修改请保持空白。

### 执行频率

**间隔执行**：每隔固定时长（1–23 小时）触发，从数据流创建时刻开始计算。

| 选项 | 适用场景 |
|------|---------|
| 每 1 小时（默认） | 适合大多数分析场景 |
| 每 2 小时 | 数据量较大时降低频率 |
| 每 6 小时 | 日常增量同步 |
| 每 12 小时 | 用户数据等更新频率较低的场景 |
| 每 24 小时 | 每日批量导出 |

**定时执行**：在指定时区的固定时刻触发，适合需要在业务低峰期执行的场景。选择时区和执行时刻后，系统将每天在该时刻触发一次。时区仅影响触发时刻的计算，详见[时区说明](#时区说明)。

## 数据模型

### 事件表（默认 `sensorswave_events`）

事件数据导出到此表，采用追加写入（Append-only）模式，按天分区。以下以默认表名为例。

| 列名 | 类型 | 说明 |
|------|------|------|
| `time` | `DateTime64(3)` | 事件发生时间 |
| `distinct_id` | `String` | 客户端用户唯一标识 |
| `trace_id` | `String` | 请求追踪 ID |
| `ssid` | `Int64` | 服务端用户唯一标识（SSID） |
| `anon_id` | `String` | 匿名 ID |
| `login_id` | `String` | 登录 ID |
| `event` | `String` | 事件名称，如 `$pageview`、`purchase` |
| `properties` | `JSONB` | 事件属性 JSON |
| `user_properties` | `JSONB` | 事件触发时的用户属性快照 JSON |
| `received_at` | `DateTime64(3)` | 服务端接收时间 |

时间列与 `properties` / `user_properties` 内日期时间字段的时区、格式详见[时区说明](#时区说明)。

查询 `JSONB` 类型属性的示例：

```sql
-- 查询事件属性中的 order_id 字段
SELECT
    time,
    event,
    jsonb_extract_string(properties, '$.order_id')     AS order_id,
    jsonb_extract_float64(properties, '$.total_amount') AS total_amount
FROM sensorswave.sensorswave_events
WHERE event = 'purchase'
  AND time >= '2026-04-01'
LIMIT 100;
```

### 用户表（默认 `sensorswave_users`）

用户数据导出到此表，采用按 `ssid` 匹配的 upsert 模式（存在则更新、不存在则插入）。

| 列名 | 类型 | 说明 |
|------|------|------|
| `ssid` | `Int64` | 服务端用户唯一标识，主键 |
| `login_id` | `String` | 登录 ID |
| `anon_id` | `String` | 匿名 ID |
| `properties` | `JSONB` | 用户属性 JSON，包含所有用户画像属性 |
| `created_at` | `DateTime64(3)` | 用户首次创建时间 |
| `updated_at` | `DateTime64(3)` | 用户属性最近更新时间 |

查询 `JSONB` 类型用户属性的示例：

```sql
-- 查询用户属性中的会员等级
SELECT
    ssid,
    login_id,
    jsonb_extract_string(properties, '$.membership_level') AS membership_level,
    updated_at
FROM sensorswave.sensorswave_users
WHERE jsonb_extract_string(properties, '$.membership_level') != ''
LIMIT 100;
```

## 时区说明

ByteHouse 数据流涉及多种时区语义，以下内容汇总了所有受时区影响的值与对应来源。

### 时区影响速览

| 值 | 时区 | 由谁决定 |
|----|------|---------|
| 时间列（`time`、`received_at`、`created_at`、`updated_at`） | SaaS 服务时区（国内 `Asia/Shanghai`，海外 `UTC`） | SensorsWave 集群，无法更改 |
| `properties` / `user_properties` 中的日期时间属性 | SaaS 服务时区（与时间列一致） | 与时间列一致 |
| 回填窗口切分时区 | SaaS 服务时区 | 固定，不可配置 |
| 定时执行触发时刻 | 用户配置时区 | 创建数据流时填写 |

### 时间列

ByteHouse 中所有 `DateTime64(3)` 列（`time`、`received_at`、`created_at`、`updated_at`）绑定 **SaaS 服务时区**，**精确到毫秒**（与 `properties` / `user_properties` 中日期时间字段的精度一致）。完整类型为 `DateTime64(3, '{system_tz}')`，其中 `{system_tz}` 根据集群自动注入：国内集群为 `Asia/Shanghai`（UTC+8），海外集群为 `UTC`。

**示例（国内集群）**：SaaS 服务时区为 `Asia/Shanghai`，某事件发生在北京时间 `2026-04-13 15:30:00.123`，ByteHouse 中 `time` 列显示为 `2026-04-13 15:30:00.123`。

该列不支持在 ByteHouse 侧转换为其他时区显示；如需按其他时区分析，请在应用层或 BI 工具中对查询结果做换算。

### JSONB 属性中的日期时间字段

如果事件或用户属性本身是日期时间类型，序列化到 `properties` / `user_properties` 后以字符串形式存储：

- **格式**：`YYYY-MM-DD HH:MM:SS.fff`（精确到毫秒，不含时区偏移）
- **时区**：与时间列一致，为 SaaS 服务时区

**示例**：`{"purchase_at": "2026-04-13 15:30:00.000"}`

### 回填窗口切分时区

ByteHouse 回填使用 **SaaS 服务时区** 切分自然日窗口（国内集群 `Asia/Shanghai`，海外集群 `UTC`），串行执行。每个窗口为 **左闭右开** 区间 `[start, end)`：包含 `start` 时刻、不包含 `end` 时刻，避免相邻窗口在边界处重复覆盖事件。

**示例（国内集群）**：回填 `2026-04-01 ~ 2026-04-03` 将按 `Asia/Shanghai` 切分为 3 个窗口（均为左闭右开）：

- 窗口 1：`[2026-04-01 00:00:00, 2026-04-02 00:00:00)`（Asia/Shanghai）
- 窗口 2：`[2026-04-02 00:00:00, 2026-04-03 00:00:00)`（Asia/Shanghai）
- 窗口 3：`[2026-04-03 00:00:00, 2026-04-04 00:00:00)`（Asia/Shanghai）

### 定时执行触发时区

配置定时执行时需指定时区。例如配置 `Asia/Shanghai` 08:00，则每天北京时间 8 点触发。该时区仅影响触发时刻计算，不影响时间列的存储值与回填窗口切分。

## 事件过滤

事件过滤仅适用于**事件数据导出**，支持以下两种模式：

- **包含事件（白名单）**：只导出列表中指定的事件，其余事件不导出
- **排除事件（黑名单）**：导出所有事件，但跳过列表中指定的事件

在**高级选项**中选择过滤模式并填写事件名称列表（如 `$pageview`、`purchase`）。

> **注意**：事件过滤修改后，在当前同步窗口完成后的下一个窗口生效，不会重新处理已导出的数据。

## 测试连接

点击**测试连接**后，系统将按以下 7 个步骤端到端验证 ByteHouse 与 TOS 配置：

1. **TCP 连接**：验证 `Host` / `Port` 可达。
2. **身份认证**：使用填写的认证方式连接 ByteHouse。
3. **Virtual Warehouse**：切换到指定的计算组（若填写了 `Virtual Warehouse`）。
4. **Database**：切换到指定的 `Database`。
5. **建表检查**：在目标 Database 下建立并清理一张临时探测表，验证建表权限。
6. **TOS 写入**：向 TOS Bucket 上传一个测试文件，验证 TOS AK/SK 权限。
7. **CnchS3 读取**：由 ByteHouse 从 TOS 读取上一步的测试文件，端到端验证 `S3` 权限与 TOS 连通性。

每一步的验证结果会实时显示，方便快速定位问题。整个测试在 3 分钟内完成。

### 常见连接错误

| 错误提示 | 可能原因 | 解决方法 |
|---------|---------|---------|
| TCP 连接失败 | `Host` 或 `Port` 错误、网络不通 | 检查 ByteHouse 实例是否开启公网访问，确认 `Host` 为控制台展示的公网地址，`Port` 使用 TCP 端口（默认 `19000`） |
| 身份认证失败 | `Account ID`、`Username` / `Password` 或 `API Key` 错误 | 核对火山引擎账号 ID 与用户凭证；IAM 认证下确认 `API Key` 未过期 |
| 无权使用 Virtual Warehouse | User 未勾选该计算组的使用权限 | 在「权限管理 → 用户」编辑 `sensorswave_user`，勾选 `sensorswave_vw` 的使用权限 |
| 无建表权限 | Role 缺少 `CREATE TABLE` 权限 | 在控制台为 `sensorswave_role` 补齐 `CREATE TABLE` / `DROP TABLE` 权限 |
| CnchS3 读取失败 | Role 未获 `S3` 权限，或 TOS AK/SK 无读取权限 | 在管理后台或 bytehouse-cli 执行 `GRANT S3, CREATE TEMPORARY TABLE ON *.* TO sensorswave_role`；检查 TOS AK/SK 的 IAM 策略 |
| TOS 写入失败 | TOS AK/SK 缺少写入权限，或 `Bucket` / `Region` 错误 | 核对 Bucket 名称与区域；补齐 AK/SK 的 TOS 写入权限 |

## 数据流管理与监控

### 数据流状态

数据流的生命周期状态如下：

```
新建 → 运行中 → 已停止（不可逆）
```

> **注意**：停止数据流是不可逆操作。停止后，所有调度将终止，不再产生新的同步任务。如需恢复导出，必须重新创建数据流。历史运行记录在停止后仍可查看。

### 查看运行记录

在数据流详情页面的**运行记录**标签页，可以查看每次同步任务的执行情况：

- **状态**：运行中（Running）/ 成功（Success）/ 失败（Failed）
- **数据范围**：本次同步覆盖的时间窗口
- **导出行数**：本次成功写入 ByteHouse 的行数
- **执行时间**：任务开始和结束时间
- **日志**：点击单条记录可展开查看详细执行日志

### 查看统计指标

**指标**标签页展示数据流的整体运行状态（默认最近 30 天）：

- 成功 / 失败运行次数趋势图
- 每日导出行数趋势图
- 支持自定义时间范围筛选

## 历史数据回填

### 什么是回填

数据流创建后，增量同步仅处理从创建时刻起的新数据。如果需要将创建时刻之前的历史数据也导入 ByteHouse，需要使用回填（Backfill）功能。

### 操作步骤

1. 进入数据流详情页，切换到**回填**标签页。
2. 点击**发起回填**，选择需要补充的日期范围（开始日期和结束日期）。
3. 确认回填日期后，点击**确认执行**。

> **注意**：回填按 **SaaS 服务时区** 切分自然日窗口，详见[时区说明](#时区说明)。

### 回填与增量同步的关系

- 回填运行期间，该数据流的增量定时同步会**自动暂停**，不会丢失数据——回填完成或取消后，增量同步从上次的位置继续
- 同一数据流同时只允许一个回填任务在运行
- 回填中断（如服务重启）后，系统自动从上次完成的窗口继续，已完成的窗口不会重复执行

### 取消回填

在回填进行中，可点击**取消**终止当前回填。取消操作在当前窗口执行完成后生效，不会中断正在进行的窗口。

## 投递语义与数据一致性

| 数据类型 | 任务类型 | 写入方式 | 投递语义 |
|---------|---------|---------|---------|
| 事件数据 | 定时增量同步 | 追加 | at-least-once |
| 事件数据 | 历史回填 | 按窗口幂等覆盖 | exactly-once（窗口内） |
| 用户数据 | 定时增量同步 / 历史回填 | 按 `ssid` 匹配更新 | exactly-once |

## 注意事项

- **停止数据流不可逆**：停止后需重新创建数据流，历史运行记录保留
- **凭证加密存储**：`Password`、`API Key`、`Secret Key` 加密存储不回显；编辑时留空表示保持不变
- **目标表自动创建**：保存数据流时，系统自动在 ByteHouse 中创建目标表；无需提前手动建表
- **回填时区**：ByteHouse 回填按 SaaS 服务时区切分自然日窗口，请据此确定回填日期范围
- **回填期间增量暂停**：回填运行期间定时增量同步暂停，回填完成后自动恢复，数据不丢失
- **时间列为本地时间**：ByteHouse 中的时间列存储 SaaS 服务时区的本地时间，不是 UTC；跨时区分析时需注意换算
- **数组属性语义**：`properties` / `user_properties` 中 `Array` 类型的属性字段，若源值为 `NULL`，导出后在 ByteHouse 中统一落为 `[]`；如业务上需要严格区分 `NULL` 与 `[]`，请在查询时避免依赖该差异
- **事件重复行**：`sensorswave_events` 原始表中可能出现少量重复行。

  **发生原因**：事件表的定时增量同步采用追加写入、at-least-once 投递语义，重复主要来自以下两个场景。

  - **场景一：增量任务故障重试**。定时增量同步在写入过程中如遇节点故障、网络异常或 ByteHouse 写入超时，会自动重试当前批次以保证不丢数据。若前一次写入实际已部分或全部成功，重试就会在事件表中追加重复行。此场景偶发，影响范围小。
  - **场景二：回填与增量叠加**。历史回填与定时增量是两条独立链路，各自独立写入。事件的 `time` 字段记录事件实际发生时间，而增量同步按事件在服务端的入库时间推进，当两条链路覆盖到同一条迟到事件时就会产生重复。如果某事件发生于 `T`、延迟到 `T + N` 才上报入库：

    1. 用户发起回填，回填窗口按事件发生时间切分，覆盖 `T`。此时该事件已在历史存储中（入库时间为 `T + N`），回填按事件时间 `T` 将其导出到 ByteHouse。
    2. 回填完成后，增量同步从上次的入库位点继续推进，到达 `T + N` 时再次将这条迟到事件导出。

  用户数据无论是定时增量还是回填，都按 `ssid` 匹配更新，投递语义为 exactly-once，不存在上述问题。

  **解决方案**：以下两种方式可任选其一，也可组合使用。

  **方案一：创建去重视图（推荐作为日常查询入口）**

  在 ByteHouse 中创建去重视图，按事件唯一标识保留最新一行：

  ```sql
  CREATE VIEW sensorswave.sensorswave_events_dedup AS
  SELECT
      time, distinct_id, trace_id, ssid, anon_id, login_id,
      event, properties, user_properties, received_at
  FROM (
      SELECT *,
             row_number() OVER (
                 PARTITION BY time, event, distinct_id, trace_id
                 ORDER BY received_at DESC
             ) AS rn
      FROM sensorswave.sensorswave_events
  )
  WHERE rn = 1;
  ```

  **方案二：仅回填 7 天之前的数据**

  服务端对迟到超过 7 天的事件不再允许入库，因此 7 天之前的时间窗口不会再有新的迟到事件通过增量同步进入 ByteHouse。将回填的结束日期限制在「当前日期 - 7 天」之前，即可从源头避免重复。如需补齐最近 7 天内的数据，建议沿用方案一通过去重视图查询。

## 常见问题

**Q：测试连接失败，提示「CnchS3 读取失败」，如何处理？**

按顺序排查三件事：

1. 是否在 ByteHouse 管理后台或 bytehouse-cli 执行过 `GRANT S3, CREATE TEMPORARY TABLE ON *.* TO sensorswave_role`；
2. TOS AK/SK 是否具备读取与 List 权限；
3. `Endpoint` / `Region` / `Bucket` 是否填写正确。

**Q：数据流已在「运行中」，能否修改连接配置或事件过滤？**

支持修改。进入数据流详情，点击**编辑**修改配置。修改在当前同步窗口完成后的下一个窗口生效；调度频率修改后立即生效。

**Q：事件表中出现重复行怎么办？**

事件表的定时增量同步使用 at-least-once 投递语义，重复主要来自两类场景：一是增量同步任务在故障重试时重复写入同一批次（偶发）；二是回填窗口覆盖了某条迟到事件的发生时间 `T`，回填按事件时间将其导出后，增量同步推进到入库时间 `T + N` 时再次导出。处理方式有两种：

- **查询侧去重**：使用上方「注意事项」中的去重视图 `sensorswave_events_dedup` 作为日常查询入口，或按 `time`、`event`、`distinct_id`、`trace_id` 四个字段组合使用 `row_number()` 去重，保留 `received_at` 最新的记录。该方式可同时覆盖上述两种来源。
- **回填侧规避**：仅回填「当前日期 - 7 天」之前的数据。服务端对迟到超过 7 天的事件不再入库，因此该范围不会再有新的迟到事件通过增量同步写入。

**Q：`properties` 和 `user_properties` 中的 `JSONB` 数据如何查询？**

使用 ByteHouse 的 `jsonb_extract_*` 系列函数，通过 JSONPath 表达式（`$.field_name`）访问嵌套字段并指定类型：

```sql
-- 字符串类型字段
SELECT jsonb_extract_string(properties, '$.page_url') FROM sensorswave.sensorswave_events;

-- 整数类型字段
SELECT jsonb_extract_int64(properties, '$.item_count') FROM sensorswave.sensorswave_events;

-- 浮点字段
SELECT jsonb_extract_float64(properties, '$.total_amount') FROM sensorswave.sensorswave_events;

-- 布尔字段
SELECT jsonb_extract_bool(properties, '$.is_vip') FROM sensorswave.sensorswave_events;
```

完整函数列表参见 [ByteHouse JSONB 类型文档](https://www.volcengine.com/docs/6517/1580784?lang=zh)。

**Q：ByteHouse 中的 `time` 列是什么时区？**

`time` 列使用 `DateTime64(3, '{system_tz}')`，绑定 SaaS 服务时区：国内集群为 `Asia/Shanghai`（UTC+8），海外集群为 `UTC`。该列不支持在 ByteHouse 侧转换为其他时区显示；如需按其他时区分析，请在应用层或 BI 工具中对查询结果做换算。

**Q：为什么要求 `GRANT S3, CREATE TEMPORARY TABLE ON *.*`？**

这两类权限在 ByteHouse 授权模型里不归属任何 Database：`S3` 属于 Source 类权限（同类还有 `URL`、`HDFS`、`MYSQL`），`CREATE TEMPORARY TABLE` 作用于会话级临时表（本身无 Database 概念）。语法上只能写成 `ON *.*`，并非授予跨库读写能力，真实数据访问仍由 `.*` 上的权限决定。

---

**最后更新时间**：2026 年 4 月 23 日