事件存储结构¶

大纲¶

您可以查看传输的事件日志如何存储在 BigQuery 中、attributes JSON 字段的详细结构以及如何隔离违反传输规则的日志。

表结构¶

发送的事件日志存储在公司专属 BigQuery 数据集的 t_raw_event_log 表中。

表列结构¶

存储位置¶

项目	格式
表	`t_raw_event_log`
分区	按 `dateTime` 每日分区

列定义¶

列名称	数据类型	是否必需	描述	示例
`userId`	STRING	Y	基于账号的用户标识符	`100001`
`identifierProvider`	STRING	Y	发放用户标识符的体系。始终为 `hive`	`hive`
`deviceId`	STRING	Y	基于设备的用户标识符	`100000`
`appId`	STRING	Y	在 Hive 控制台 > 应用中心注册的项目 ID	`"com.com2us.game.ios"`
`appIdGroup`	STRING	Y	Hive 控制台 > 应用中心发放的游戏 ID。基于 `appId` 转换的值	`com.com2us.game`
`dateTime`	TIMESTAMP	Y	事件发生的时间。将 `eventTime` 转换为 UTC 的值	`2026-07-20T05:01:01Z`
`eventName`	STRING	Y	用于区分事件的事件名称	`asset_drop`
`checksum`	STRING	N	排除管道注入或系统生成的所有字段（如 `hiveAttributes` 等），仅基于客户发送的原始数据生成的哈希值	`HW2FTEB56TEEWER`
`bigqueryRegistTimestamp`	TIMESTAMP	N	事件存储到 BigQuery 的 UTC 时间	`2026-07-20T05:02:01Z`
`attributes`	JSON	N	存储自定义属性和自动收集属性的 JSON 字段	见下文

表结构注意事项 & Tips¶

同一事件可能会因重传等原因而被重复存储，因此搜索时建议使用基于 checksum 的去重查询。
```
QUALIFY ROW_NUMBER() OVER (PARTITION BY checksum ORDER BY bigqueryRegistTimestamp DESC) = 1
```
违反传输规则的事件日志存储在 rescue 表中，而不是此表中。有关详细信息，请参阅数据隔离。

attributes 详细属性¶

Note

attributes 列的类型为 JSON，分为两个区域：hiveAttributes 和 eventAttributes。

attributes 示例¶

{
  "hiveAttributes": {
    "_clientIp": "220.70.82.0",
    "_dataSource": "custom_server",
    "_fluentd_appid": "com.com2us.game.ios",
    "_fluentd_sender_ip": "43.101.101.33",
    "_fluentd_hostaname": "9104813d31ab",
    "_fluentd_tag": "ha2union.game.stage",
    "_geoIpCountry": "KR",
    "_market": "google",
    "_os": "android"
  },
  "eventAttributes": {
    "eventTime": "2026-07-20T14:01:01+09:00",
    "level": 10,
    "character_name": "AA",
    "stage_id": "stage_101"
  }
}

hiveAttributes¶

这是管道自动处理和存储的区域。

属性名称	数据类型	描述	示例
`_clientIp`	STRING	日志中发送了 `client_ip` 或 `clientIp` 时，将所发送 IP 的最后一段改为 0 的值。未发送 `client_ip` 或 `clientIp` 时不生成	`220.70.82.0`
`_geoIpCountry`	STRING	管道根据 `client_ip` 或 `clientIp` 判断的国家/地区代码（ISO 3166 alpha-2）。未发送 `client_ip` 或 `clientIp` 时不生成	`KR`
`_dataSource`	STRING	管道判断的事件日志实际传入的路径。请参阅下面的 `_dataSource` 详细信息	`custom_server`
`_fluentd_appid`	STRING	管道判断的日志收集器（Fluentd）的 appId	`com.com2us.game.ios`
`_fluentd_sender_ip`	STRING	管道判断的日志收集器（Fluentd）的 IP	`43.101.101.33`
`_fluentd_hostaname`	STRING	管道判断的日志收集器（Fluentd）的主机名	`9104813d31ab`
`_fluentd_tag`	STRING	管道判断的发送到日志收集器（Fluentd）的标签名称	`ha2union.game.stage`
`_market`	STRING	Analytics 根据 appId 判断的市场信息	`google`
`_os`	STRING	Analytics 根据 appId 判断的 OS 信息	`android`

_dataSource 详细信息¶

_dataSource 表示事件日志实际传入的路径，并自动设置为以下值之一：

值	描述
`airbridge`	通过 Airbridge 收集的事件
`appsflyer`	通过 Appsflyer 收集的事件
`adjust`	通过 Adjust 收集的事件
`singular`	通过 Singular 收集的事件
`hive_server`	通过 Hive 认证、结算等自动收集的事件
`hive_sdk`	Hive SDK 自动收集的漏斗等事件
`custom_server`	客户从服务器发送的自定义事件
`custom_sdk`	客户通过 Hive SDK 的事件日志发送功能发送的自定义事件
`custom_sdk_mig`	客户通过 Hive SDK 的事件日志发送功能发送到旧版 Analytics 的自定义事件
`custom_server_mig`	客户从服务器发送到旧版 Analytics 的自定义事件
`custom_except`	在事件转换过程中作为例外情况生成并传输 `eventAttribute`、`hiveAttribute` 的事件

eventAttributes¶

这是存储用户发送的属性和 SDK 自动收集的属性的区域。

属性名称	数据类型	描述
`eventTime`	STRING	作为必需属性发送的 `eventTime` 原始值
（用户定义的属性）	数字/字符	用户直接发送的自定义属性
（自动收集的属性）	因属性而异	SDK 自动收集的客户端信息（客户端传输时）

attributes 注意事项 & Tips¶

hiveAttributes 不是开发者直接设置值的区域，而是管道自动填充的区域。除 _clientIp、_dataSource、_fluentd_appid、_fluentd_sender_ip、_fluentd_hostaname、_fluentd_tag、_geoIpCountry、_market、_os 以外的值不会被保存。
自定义属性和 SDK 自动收集的属性一起存储在 eventAttributes 中。搜索时，必须通过属性名称来区分。
您可以使用 _dataSource 值区分事件日志的传输路径（SDK/服务器/MMP 等）进行搜索。

数据隔离¶

Warning

不符合传输规则的事件日志不会存储在普通表 (t_raw_event_log) 中，而是单独存储在隔离表 (t_raw_event_log_rescue) 中。隔离表保留原始 JSON，因此您可以确定隔离的原因、修复它并重新传输。

隔离原因¶

错误原因	描述	如何应对
缺少必需属性	7 个必需属性（`userId`、`identifierProvider`、`deviceId`、`appId`、`appIdGroup`、`eventTime`、`eventName`）中的任何一个缺失或为空值	补充缺少的必需属性后重新发送
使用保留字	将 `attributes`、`eventAttributes`、`hiveAttributes` 用作属性名称时（不区分大小写）	将属性名称更改为其他名称
不允许的属性值	属性值为 JSON 对象 (`{}`) 或 JSON 数组 (`[]`) 形式时	将属性值更改为字符串或数字
eventTime 格式错误	`eventTime` 不是 RFC 3339 格式或无法解析	修改为 RFC 3339 格式（含时区）
eventTime 超出范围	`eventTime` 超出以当前时间为基准的过去 10 年至未来 5 年范围	检查 eventTime 值并修改至正常范围
JSON 解析失败	发送的消息不是有效的 JSON 格式	验证 JSON 格式并重新发送

隔离表结构¶

隔离的事件日志以如下结构存储在 t_raw_event_log_rescue 表中。各列仅在原始 JSON 可以解析时才会填充，否则存储为空值。原始内容可在 rawData 中确认。

列名称	数据类型	描述
`userId`	STRING	发送的 userId
`identifierProvider`	STRING	发送的 identifierProvider
`deviceId`	STRING	发送的 deviceId
`appIdGroup`	STRING	发送的 appIdGroup
`dateTime`	STRING	传输的 eventTime 原始值（以字符串存储，而不是 TIMESTAMP）
`eventName`	STRING	发送的 eventName
`bigqueryRegistTimestamp`	TIMESTAMP	日志存储到 BigQuery 的时间
`checksum`	STRING	排除管道注入或系统生成的所有字段（如 `hiveAttributes` 等），仅基于客户发送的原始数据生成的哈希值
`rawData`	STRING	发送的全部原始 JSON
`errorReason`	STRING	隔离原因代码。请参阅隔离原因代码
`errorStackTrace`	STRING	隔离详细信息（缺少的字段名称等）

隔离原因代码¶

error_code	error_key	条件
100	`JSON_PARSE_ERROR`	JSON 解析失败
200	`DATETIME_MISSING`	`dateTime` 字段缺失或为空
201	`DATETIME_INVALID`	`dateTime` 无法解析
—	`DATASOURCE_MISSING`	`_dataSource` 为 null 或未定义的值

隔离日志查询示例¶

可以在 BigQuery 中直接查询隔离的日志。要使用 BigQuery 查询，必须先申请 BigQuery 权限。

SELECT
  errorReason,
  errorStackTrace,
  eventName,
  dateTime,
  rawData,
  bigqueryRegistTimestamp
FROM `habq-storage.analytics_N_live.t_raw_event_log_rescue`
WHERE appIdGroup = 'com.sample.test'  -- 实际使用的 appIdGroup
LIMIT 100;