โครงสร้างการจัดเก็บเหตุการณ์¶

โครงร่าง¶

คุณสามารถดูวิธีการจัดเก็บบันทึกเหตุการณ์ที่ส่งใน BigQuery โครงสร้างโดยละเอียดของฟิลด์ JSON attributes และวิธีการกักกันบันทึกที่ละเมิดกฎการส่ง

โครงสร้างตาราง¶

บันทึกเหตุการณ์ที่ส่งจะถูกจัดเก็บไว้ในตาราง t_raw_event_log ในชุดข้อมูล BigQuery เฉพาะบริษัท

โครงสร้างคอลัมน์ตาราง¶

สถานที่จัดเก็บ¶

รายการ	รูปแบบ
ตาราง	`t_raw_event_log`
การแบ่งพาร์ติชัน	พาร์ติชันรายวันตาม `dateTime`

คำจำกัดความของคอลัมน์¶

ชื่อคอลัมน์	ชนิดข้อมูล	จำเป็น	คำอธิบาย	ตัวอย่าง
`userId`	STRING	Y	ตัวระบุผู้ใช้ตามบัญชี	`100001`
`identifierProvider`	STRING	Y	ระบบที่ออกตัวระบุผู้ใช้ เป็น `hive` เสมอ	`hive`
`deviceId`	STRING	Y	ตัวระบุผู้ใช้ตามอุปกรณ์	`100000`
`appId`	STRING	Y	Project ID ที่ลงทะเบียนใน Hive Console > App Center	`"com.com2us.game.ios"`
`appIdGroup`	STRING	Y	Game ID ที่ออกโดย Hive Console > App Center ค่าที่แปลงตาม `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	เวลา UTC ที่เหตุการณ์ถูกจัดเก็บใน BigQuery	`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	appId ของตัวรวบรวมบันทึก (Fluentd) ตามที่ไปป์ไลน์กำหนด	`com.com2us.game.ios`
`_fluentd_sender_ip`	STRING	IP ของตัวรวบรวมบันทึก (Fluentd) ตามที่ไปป์ไลน์กำหนด	`43.101.101.33`
`_fluentd_hostaname`	STRING	ชื่อโฮสต์ของตัวรวบรวมบันทึก (Fluentd) ตามที่ไปป์ไลน์กำหนด	`9104813d31ab`
`_fluentd_tag`	STRING	ชื่อแท็กที่ส่งไปยังตัวรวบรวมบันทึก (Fluentd) ตามที่ไปป์ไลน์กำหนด	`ha2union.game.stage`
`_market`	STRING	ข้อมูลมาร์เก็ตที่ Analytics กำหนดจาก appId	`google`
`_os`	STRING	ข้อมูล OS ที่ Analytics กำหนดจาก appId	`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`	เหตุการณ์ที่กำหนดเองที่ลูกค้าส่งไปยัง Analytics เวอร์ชันเก่าผ่านคุณสมบัติส่งบันทึกเหตุการณ์ใน Hive SDK
`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 เมื่อค้นหาจะต้องจำแนกตามชื่อแอตทริบิวต์
คุณสามารถค้นหาโดยแยกแยะเส้นทางการส่งของบันทึกเหตุการณ์ (SDK/เซิร์ฟเวอร์/MMP ฯลฯ) โดยใช้ค่า _dataSource

การแยกข้อมูล¶

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;

เมนูที่เกี่ยวข้อง¶

ส่งคุณสมบัติเหตุการณ์ — กฎโดยละเอียดสำหรับคุณสมบัติที่จำเป็น/รวบรวมโดยอัตโนมัติ/กำหนดแบบกำหนดเอง
การส่งบันทึกเหตุการณ์ — วิธีการส่งข้อมูลผ่าน Hive SDK v4, Fluentd, HTTP