GitHub 行为数据库说明

数据本身源自Github Archive项目。 GitHub Archive 是 GitHub 提供的公开事件数据集，记录了 GitHub 上所有用户行为（如提交、问题、拉取请求等，非面板数据）。如果财力足够可以直接选择使用Google BigTable进行查询。本实现将归档数据载入Clickhouse并通过展平优化查询，达到和BigTable一致的查询体验与近似的查询性能。

如果需要当前面板数据可以直接通过仓库对应 API 链接获取；历史面板数据大部分能够通过行为数据进行反推。

具体数据缺陷见 https://option.cv/gharchive-traps/ 。缺陷来自于GitHub Archive或GitHub本身，因此即便是BigTable也存在同样数据缺失。

1. 数据模型概述

GitHub Archive 的数据模型以 事件（Event） 为核心，每个事件对应一行数据（Row），包含以下核心信息：

事件类型（Event Type）：事件的分类（如 PushEvent、CreateEvent、IssueEvent 等）。
元数据（Metadata）：事件的上下文信息（如时间戳、用户信息、仓库信息等）。
事件内容（Payload）：事件的具体数据（如提交内容、问题描述、拉取请求详情等）。

2. 数据模型 Schema

当前落地实现使用 ClickHouse 单表展平：每条 GitHub Archive 事件对应一行；将高频过滤/聚合字段（时间、actor/repo/org、public、event_type）拆成独立列，原始事件 JSON 以字符串形式保存在 payload（以及补充字段 other）中。

下面按“列（字段）”逐个解释其含义与常见取值。

2.1 字段逐项说明

字段	含义	默认值	备注
`id`	事件唯一标识	-	同一事件可能被重放/补采；下游常用 `id` 参与去重
`event_type`	事件类型（如 `PushEvent`、`PullRequestEvent`）	-	解析 `payload` 的入口
`actor_id`	事件发起者（actor）ID	-	按字符串保存以贴近上游 JSON
`actor_login`	actor 的用户名（login）	`''`	缺失时为空字符串
`actor_display_login`	actor 展示名	`''`	某些数据源会提供
`actor_gravatar_id`	actor 的 gravatar id（历史字段）	`''`	现代数据中可能经常为空
`actor_url`	actor 的 API URL	`''`	取决于源数据
`actor_avatar_url`	actor 头像 URL	`''`	取决于源数据
`repository_id`	事件关联仓库 ID	-
`repository_name`	仓库名（通常为 `owner/name`）	`''`	取决于源数据
`repository_url`	仓库 API URL	`''`	取决于源数据
`org_id`	组织 ID（若适用）	`''`	不适用时为空字符串
`org_login`	组织 login（组织名）	`''`	不适用时为空字符串
`org_gravatar_id`	组织 gravatar id（历史字段）	`''`
`org_url`	组织 API URL	`''`	不适用时为空字符串
`org_avatar_url`	组织头像 URL	`''`	不适用时为空字符串
`created_at`	事件发生时间（UTC）	-	用于时间窗分析、增量抽取
`public`	是否公开可见	-	由数据源给出
`payload`	事件 payload（原始 JSON 字符串）	-	结构随 `event_type` 变化，详见第 3 节
`other`	其他未展平字段（原始 JSON 字符串）	-	用于兜底保留额外信息，减少 schema 变更

3. `payload` 字段说明（对应 GitHub 文档）

payload 保存的是事件的原始 JSON（字符串形式）。它的结构完全由 event_type 决定，因此必须先看事件类型，再决定解析哪些字段。

GitHub 官方对事件类型与 payload 结构的入口页：
- https://docs.github.com/en/webhooks-and-events/events/github-event-types

下面按常见事件类型给出“文字解释 + 字段表”。字段路径以 payload JSON 内部的 key 为准（如 commits[].sha 表示 commits 数组里每个元素的 sha）。

3.1 `PushEvent`

PushEvent 表示向仓库分支或标签推送提交。

字段路径	含义	类型	备注
`repository_id`	发生 push 的仓库 ID	Integer
`push_id`	push 的唯一标识	Integer
`ref`	被 push 的完整 ref	String	例如 `refs/heads/main`
`head`	push 后 ref 的最新提交 SHA	String
`before`	push 前 ref 的最新提交 SHA	String

3.2 `CreateEvent`

CreateEvent 表示创建分支、标签或仓库等（以 ref_type 区分）。

字段路径	含义	类型	备注
`ref`	被创建的引用名	String	例如分支名或 tag 名
`ref_type`	创建对象类型	String	常见：`branch` / `tag` / `repository`
`full_ref`	完整 ref	String	分支通常为 `refs/heads/<branch_name>`
`master_branch`	默认分支名	String	并非总是存在
`description`	仓库描述	String	创建仓库时更常见
`pusher_type`	推送者类型	String	例如 `user`

3.3 `DeleteEvent`

DeleteEvent 表示删除分支或标签。

字段路径	含义	类型	备注
`ref`	被删除的引用名	String	分支名或 tag 名
`ref_type`	删除对象类型	String	常见：`branch` / `tag`
`full_ref`	完整 ref	String	分支通常为 `refs/heads/<branch_name>`
`pusher_type`	推送者类型	String	例如 `user`

3.4 `ForkEvent`

ForkEvent 表示用户 fork 了一个仓库。

字段路径	含义	类型	备注
`action`	动作	String	`forked`
`forkee`	fork 后创建出的仓库对象	Object	完整结构见仓库资源定义

3.5 `IssuesEvent`

该事件表示 issue 被打开/关闭/重新打开/编辑等，通常通过 action 区分动作。

字段路径	含义	类型	备注
`action`	动作	String	`opened` / `closed` / `reopened`
`issue`	issue 对象	Object
`assignee`	可选：被指派/取消指派的用户	Object
`assignees`	可选：issue 上的 assignees 数组	Array
`label`	可选：被添加/移除的 label	Object
`labels`	可选：labels 数组	Array

3.6 `IssueCommentEvent`

该事件表示在 issue（或 PR 作为 issue）下新增/编辑/删除评论。

字段路径	含义	类型	备注
`action`	动作	String	`created`
`issue`	issue 对象	Object	用于定位评论所属 issue
`comment`	评论对象	Object	重点字段：id/body/user/created_at

3.7 `PullRequestEvent`

该事件表示 PR 的生命周期事件（开启、关闭、合并、同步、编辑等）。payload 核心在 action 与 pull_request 对象。

字段路径	含义	类型	备注
`action`	动作	String	`opened` / `closed` / `merged` / `reopened` / `assigned` / `unassigned` / `labeled` / `unlabeled`
`number`	PR 编号	Integer
`pull_request`	PR 对象	Object
`assignee`	可选：被指派/取消指派的用户	Object
`assignees`	可选：assignees 数组	Array
`label`	可选：被添加/移除的 label（当 action 为 labeled/unlabeled）	Object
`labels`	可选：labels 数组（当 action 为 labeled/unlabeled）	Array

3.8 `CommitCommentEvent`

该事件表示对某个 commit 的评论。

字段路径	含义	类型	备注
`action`	动作	String	`created`
`comment`	commit comment 对象	Object

3.9 `GollumEvent`

该事件表示 Wiki 页面被创建或更新。payload 核心是 pages[] 数组。

字段路径	含义	类型	备注
`pages`	页面变更列表	Array
`pages[][page_name]`	页面名	String
`pages[][title]`	页面标题	String
`pages[][summary]`	可选：页面摘要说明	String	可为 null
`pages[][action]`	动作	String	`created` / `edited`
`pages[][sha]`	页面最新提交 SHA	String
`pages[][html_url]`	页面 HTML 地址	String

3.10 `WatchEvent`

该事件表示用户 star（关注）仓库。绝大多数情况下 action 为 started。

字段路径	含义	类型	备注
`action`	动作	String	`started`

3.11 `DiscussionEvent`

DiscussionEvent 表示仓库中创建了一个 discussion。

字段路径	含义	类型	备注
`action`	动作	String	`created`
`discussion`	discussion 对象	Object

3.12 `MemberEvent`

MemberEvent 表示与仓库协作者相关的事件。

字段路径	含义	类型	备注
`action`	动作	String	`added`（表示用户接受仓库邀请）
`member`	被添加的用户对象	Object

3.13 `PublicEvent`

PublicEvent 表示私有仓库被设置为公开。

字段路径	含义	类型	备注
-	空 payload	Object	官方说明该事件返回空 `payload` 对象

3.14 `PullRequestReviewEvent`

PullRequestReviewEvent 表示 PR review 相关事件。

字段路径	含义	类型	备注
`action`	动作	String	`created` / `updated` / `dismissed`
`pull_request`	review 所属 PR 对象	Object
`review`	被影响的 review 对象	Object

3.15 `PullRequestReviewCommentEvent`

PullRequestReviewCommentEvent 表示 PR review comment（diff 评论）相关事件。

字段路径	含义	类型	备注
`action`	动作	String	`created`
`pull_request`	评论所属 PR 对象	Object
`comment`	评论对象	Object

3.16 `ReleaseEvent`

ReleaseEvent 表示 release 相关事件。

字段路径	含义	类型	备注
`action`	动作	String	`published`
`release`	release 对象	Object

5. 2015 之前的 API 数据简介

github.timeline 是 GitHub 早期的 API 标准（timeline 风格），随后逐步被基于事件的 Event 模型取代。

5.1 通用列

字段	含义	类型	备注
`event_type`	事件类型	LowCardinality(String)	解析 `payload` 的入口
`created_at`	事件发生时间（UTC）	DateTime(‘UTC’)	分区与时间窗过滤的主键之一
`public`	是否公开	Bool	同 GitHub Archive 定义
`payload`	原始事件 JSON（字符串）	String	结构随 `event_type` 变化
`other`	其他未展平字段（字符串）	String	兜底保留附加信息

5.2 参与者（Actor）字段逐项说明

字段	含义	类型	备注
`actor_id`	参与者 ID	String	与上游 JSON 一致（字符串化）
`actor_type`	参与者类型	LowCardinality(String)	如 `User` 等
`actor_login`	用户名（login）	String	常用主键
`actor_url`	用户 API URL	String	旧式 REST 路径
`actor_name`	展示名	String	旧数据中可能为空
`actor_blog`	个人站点	String	旧字段，噪声较多
`actor_company`	公司	String	旧字段，非标准化
`actor_email`	邮箱	String	通常为空或不可靠
`actor_avatar_url`	头像 URL	String
`actor_gravatar_id`	Gravatar ID	String	历史字段，现代数据少见
`actor_location`	地理位置	String	非结构化文本

5.3 仓库（Repository）字段逐项说明

字段	含义	类型	备注
`repository_id`	仓库 ID	String
`repository_name`	仓库名（`owner/name`）	String
`repository_full_name`	仓库全名	String	与 `owner/name` 等价/近似
`repository_url`	仓库 API URL	String	旧式 REST 路径
`repository_archive_url`	Archive 资源 URL	String
`repository_blobs_url`	Blobs 资源 URL	String
`repository_branches_url`	Branches 资源 URL	String
`repository_clone_url`	Git 克隆 URL	String
`repository_collaborators_url`	Collaborators 资源 URL	String
`repository_comments_url`	Comments 资源 URL	String
`repository_commits_url`	Commits 资源 URL	String
`repository_compare_url`	Compare 资源 URL	String
`repository_contents_url`	Contents 资源 URL	String
`repository_contributors_url`	Contributors 资源 URL	String
`repository_created_at`	仓库创建时间	Nullable(DateTime(‘UTC’))	可能为空
`repository_default_branch`	默认分支名	String
`repository_description`	仓库描述	String	非结构化文本
`repository_downloads_url`	Downloads 资源 URL	String	旧特性
`repository_events_url`	Events 资源 URL	String
`repository_fork`	是否为 fork	Bool
`repository_forks_count`	Fork 数	Nullable(Int32)	旧计数快照
`repository_forks_url`	Forks 资源 URL	String
`repository_git_commits_url`	Git commits URL	String
`repository_git_refs_url`	Git refs URL	String
`repository_git_tags_url`	Git tags URL	String
`repository_git_url`	Git 协议 URL	String
`repository_has_downloads`	是否开启下载	Nullable(Bool)	旧特性
`repository_has_issues`	是否开启 issues	Nullable(Bool)
`repository_has_pages`	是否开启 Pages	Nullable(Bool)
`repository_has_projects`	是否开启 Projects	Nullable(Bool)
`repository_has_wiki`	是否开启 Wiki	Nullable(Bool)
`repository_homepage`	主页	String
`repository_hooks_url`	Hooks 资源 URL	String
`repository_html_url`	仓库网页 URL	String
`repository_comment_url`	单条评论 URL 模板	String
`repository_issues_url`	Issues 资源 URL	String
`repository_keys_url`	Keys 资源 URL	String
`repository_labels_url`	Labels 资源 URL	String
`repository_language`	主要语言	String	旧字段，可能与现代统计不一致
`repository_languages_url`	Languages 资源 URL	String
`repository_master_branch`	master 分支名	String	历史字段
`repository_merges_url`	Merges 资源 URL	String
`repository_milestones_url`	Milestones 资源 URL	String
`repository_mirror_url`	镜像 URL	String	已较少使用
`repository_notifications_url`	Notifications 资源 URL	String
`repository_open_issues_count`	开放 issue 数	Nullable(Int32)	旧计数快照
`repository_organization`	组织名	String	可能为空
`repository_owner`	所有者	String
`repository_private`	是否私有	Nullable(Bool)
`repository_pulls_url`	Pulls 资源 URL	String
`repository_pushed_at`	最近 push 时间	Nullable(DateTime(‘UTC’))
`repository_releases_url`	Releases 资源 URL	String
`repository_size`	仓库大小	Nullable(Int32)	旧计量
`repository_ssh_url`	SSH URL	String
`repository_stargazers_count`	Star 数	Nullable(Int32)	旧计数快照
`repository_stargazers_url`	Stargazers 资源 URL	String
`repository_statuses_url`	Statuses 资源 URL	String
`repository_subscribers_url`	Subscribers 资源 URL	String
`repository_subscription_url`	Subscription 资源 URL	String
`repository_svn_url`	SVN URL	String	历史兼容
`repository_tags_url`	Tags 资源 URL	String
`repository_teams_url`	Teams 资源 URL	String
`repository_trees_url`	Trees 资源 URL	String
`repository_updated_at`	最近更新时间	Nullable(DateTime(‘UTC’))
`repository_watchers_count`	Watchers 数	Nullable(Int32)	旧计数快照
`repository_integrate_branch`	integrate 分支名	String	历史字段
`repository_assignees_url`	Assignees 资源 URL	String
`repository_issue_comment_url`	Issue 评论 URL 模板	String
`repository_issue_events_url`	Issue 事件 URL	String

注意：许多字段属于旧版 API 或历史语义，计数类与现代事件数据可能不完全一致；*_url 多为旧式 REST 模板，仅用于参考；隐私相关列（如 actor_email）在公开数据中通常为空。

GitHub 行为数据库说明

1. 数据模型概述

2. 数据模型 Schema

2.1 字段逐项说明

3. payload 字段说明（对应 GitHub 文档）

3.1 PushEvent

3.2 CreateEvent

3.3 DeleteEvent

3.4 ForkEvent

3.5 IssuesEvent

3.6 IssueCommentEvent

3.7 PullRequestEvent

3.8 CommitCommentEvent

3.9 GollumEvent

3.10 WatchEvent

3.11 DiscussionEvent

3.12 MemberEvent

3.13 PublicEvent

3.14 PullRequestReviewEvent

3.15 PullRequestReviewCommentEvent

3.16 ReleaseEvent