拓冰网站定制 
PostHog 数据模型参考system.integrations 第三方服务集成表深度解析【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog导读system.integrations是 PostHog 中记录第三方服务连接的system.*系统表是查询侧了解当前项目接入了哪些外部服务的唯一数据入口。本文以该表的完整字段定义为骨架结合仓库中 Integration 模型 的实现源码逐列讲解表结构、集成类型kinds、敏感配置加密机制与唯一约束并给出可直接套用的查询示例。读完你既能用 SQL 高效检索集成元数据也能理解这些连接在 PostHog 内部是如何被存储和管理的。一、认识 system.integrations第三方连接的数据底座PostHog 通过集成Integration把外部服务Slack、GitHub、Salesforce、各类广告平台等接入到产品分析流程中。system.integrations正是这些连接的按项目Team维度的元数据视图一条记录代表一个到外部服务的连接例如一个 Slack 工作区、一个 GitHub App 安装、一个 Salesforce 组织。在 querying-posthog-data 技能的数据模型参考体系中该表属于system.*系统实体表主要服务于以下场景确认某项目是否已接入某种外部服务如有没有配 Slack 集成结合kind与errors排查集成健康状态如广告平台 token 失效与 Hog 函数、批量导出、工作流Workflows等消费外部服务的实体做关联分析。底层上该表对应 Django 的 Integration 模型。需要强调的是该模型刻意不对外暴露加密凭证表内只保存非敏感元数据具体机制见下文第四节。二、表结构列定义与类型详解system.integrations的完整列定义如下与仓库文档一致ColumnTypeNullableDescriptionidintegerNOT NULL主键自动生成team_idintegerNOT NULL该集成所属的团队项目kindvarchar(32)NOT NULL集成类型标识见下文 Kinds 列表integration_idtextNULL外部系统中的标识如 Slack 工作区 ID、GitHub installation IDconfigjsonbNOT NULL非敏感、随 kind 而异的配置errorstextNOT NULL集成出问题时的错误信息无问题则为空字符串created_attimestamp with tzNOT NULL创建时间戳created_by_idintegerNULL创建者用户 ID对照源码可以确认各列的实际落点model.pyteam/team_id外键指向Teamon_deletemodels.CASCADE团队被删除时集成记录随之级联删除kindCharField(max_length32)对应IntegrationKind枚举值integration_idTextField(nullTrue, blankTrue)保存外部系统侧的唯一标识configJSONField(defaultdict)注释明确任何可以安全传给前端的配置Any config that COULD be passed to the frontendsensitive_configEncryptedJSONField——这是刻意不暴露的加密字段表中无对应列errorsTextField()无默认值非空字符串即表示存在错误created_atDateTimeField(auto_now_addTrue)创建时自动写入created_by外键指向Useron_deletemodels.SET_NULL用户被删除后该字段置空。三、Integration Kinds受支持的集成类型kind是集成表的分类键当前支持以下值slack、salesforce、hubspot、google-pubsub、google-cloud-storage、google-ads、google-sheets、google-cloud-service-account、snapchat、linkedin-ads、reddit-ads、tiktok-ads、bing-ads、intercom、email、linear、github、gitlab、meta-ads、twilio、clickup、vercel、databricks、azure-blob、firebase、jira、pinterest-ads从功能角度可以这样归类理解消息与协作slack、email、twilioCRM 与客服salesforce、hubspot、intercom代码托管与研发工具github、gitlab、linear、jira、clickup广告平台google-ads、meta-ads、snapchat、linkedin-ads、reddit-ads、tiktok-ads、bing-ads、pinterest-ads云存储 / 数据 / 消息google-pubsub、google-cloud-storage、google-cloud-service-account、google-sheets、databricks、azure-blob、firebase、vercel。值得注意这是查询system.integrations表时核心且常见的 kind 集合而源码中 IntegrationKind 枚举 的完整定义远不止这些还包含anthropic、apnsApple 推送、aws-redshift、aws-s3、s3-compatible、postgresql、snowflake、stripe、resend、google-analytics、google-calendar、youtube-analytics、customerio-*等。从源码结构可以推断枚举更全是因为其中一部分如数据仓库 / 存储类主要服务于批量导出等内部管道而slack-posthog-code已被注释明确标注为弃用Deprecated——运行时不再创建或读取该 kind。查询该表时应以文档列出的 27 个 kind 为权威集合。四、敏感配置隔离config 与加密的 sensitive_config这是该表设计中最重要的安全边界。文档明确指出sensitive_config加密的凭证、token被刻意不暴露在该表中。两者分工如下config非敏感的、kind 专属的结构化元数据如账户名account.name、工作区 ID、AWS 账户 ID、区域region等可以安全地渲染到前端sensitive_config存放access_token、refresh_token等真正的凭证使用 EncryptedJSONFieldFernet 对称加密落库仅在后端按需解密。源码对此提供了更细的实现证据模型通过field_access_control将kind、integration_id、config、sensitive_config均限制为 project 级 admin 权限可读model.pysensitive_config设置了ignore_decrypt_errorsTrue以兼容加密机制引入前写入的旧数据模型暴露了access_token与refresh_token两个只读属性均经由_decrypted_sensitive_value()读取model.py该方法会剥离可能的重复加密层read-then-save 可能造成双重加密并在所有密钥都无法解开时抛出UndecryptedIntegrationSecretError——该错误信息面向用户呈现We couldnt read the saved credentials for this connection. Reconnect the account to start syncing again.无法读取该连接的已保存凭证请重新连接账户以恢复同步并配套 Prometheus 计数器integration_sensitive_config_decrypt_recovery按kind、result统计恢复 / 不可读两类结果用于监控真实凭证是否正在丢失。因此在 SQL 侧你永远不会看到 token 等敏感数据——这正是查询该表可以放心用于审计与展示的前提。五、唯一约束与索引数据完整性的保障文档强调每个(team_id, kind, integration_id)组合是唯一的。源码用数据库层约束落实了这一点唯一约束posthog_integration_kind_id_unique字段组合为team、kind、integration_idmodel.py——同一项目内同一个外部服务标识不会出现重复连接记录辅助索引posthog_integration_kind_ext字段组合为kind、integration_id——为按类型 外部 ID 反查集成的典型查询例如按 GitHub installation ID 查找集成提供索引支撑。与之配套IntegrationManager 提供了first_github_for_team_installation、first_github_for_user_installation等便捷查询方法利用IntegrationQuerySet.for_github_installation_id()对config__installation_id同时匹配字符串与整数两种类型避免类型不一致导致的漏查。六、数据关系Team 与下游消费者文档给出两条关键关系集成归属于 Teamteam_id每条记录都挂在某个具体项目下配合唯一约束天然形成项目 → 外部服务的映射视图集成被 Hog 函数、批量导出Batch exports和工作流Workflows引用这三类实体在运行时需要真正调用外部服务集成记录提供的是连接元数据与后端持有的加密凭证。查询时如需哪些 Hog 函数 / 批量导出正在使用某个 Slack 或 GitHub 连接可以从对应实体的模型入手做反向关联。此外created_by_id源码中的created_by外键记录连接由哪位用户授权建立可用于审计谁接入了这个服务。七、集成是如何创建的OAuth 流与文件上传文档明确指出大多数集成是通过 OAuth 流程或文件上传创建的而非直接 API 调用。这解释了为什么该表本质上是事实的记录器而不是创建入口。源码佐证了这两条创建路径OAuth 流程oauth.py 中的OauthIntegration类定义了supported_kinds文档中的大部分 kind 都在其列并通过authorize_url()生成授权跳转地址、在回调后换取并保存 tokenrefresh_access_token()oauth.py负责 token 过期后的静默续期续期失败时会写入ERROR_TOKEN_REFRESH_FAILED定义于 common.py——这也解释了errors列为何可能非空文件上传如 Google 云服务账号google-cloud-service-account等类型通过上传 JSON 凭证文件建立连接AWS 类集成aws-s3等则保存 access key / role 等配置。每种 kind 的展示名由模型的display_name属性计算model.py例如 GitHub 取config.account.name、Pinterest 优先取config.business_name、Snowflake 拼接账户 认证方式未命中规则时回退到ID: integration_id。因此config的内容虽然随 kind 变化但总会包含用于前端展示的账户 / 工作区 / 业务名等信息。八、实战查询示例以下是基于表结构的可直接运行的查询示例假设通过posthog:execute-sql执行1. 查看某项目接入了哪些集成SELECT kind, integration_id, created_at, errors FROM system.integrations WHERE team_id 1 ORDER BY created_at DESC2. 按类型统计项目内的集成分布SELECT kind, COUNT(*) AS integration_count FROM system.integrations WHERE team_id 1 GROUP BY kind ORDER BY integration_count DESC3. 找出存在错误如 token 失效的集成SELECT id, kind, integration_id, errors FROM system.integrations WHERE team_id 1 AND errors 4. 查找某个 GitHub 连接的记录GitHub 以安装 ID 作为integration_idSELECT id, kind, config FROM system.integrations WHERE team_id 1 AND kind github AND integration_id 123456785. 最近 30 天内新建立的连接SELECT id, kind, integration_id, created_at, created_by_id FROM system.integrations WHERE team_id 1 AND created_at now() - INTERVAL 30 DAY ORDER BY created_at DESC九、查询注意事项小结sensitive_config不可见任何凭证、token 都不会出现在该表中查询结果天然适合展示与审计config结构随 kind 而异可能包含账户名、工作区 ID 等非机密元数据具体键名请结合对应 kind 的 provider 模块如 github.py、google_cloud.py确认唯一性语义(team_id, kind, integration_id)三元组唯一同一项目不会存在两条指向同一外部服务的同类连接errors为空字符串即健康非空表示该连接存在问题典型如 token 刷新失败排查集成类问题时可优先筛选此列创建入口不在 API连接通常经 OAuth 授权或文件上传建立直接向该表写入记录并不能获得可用凭证。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PostHog 数据模型参考：system.integrations 第三方服务集成表深度解析
PostHog 数据模型参考system.integrations 第三方服务集成表深度解析【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog导读system.integrations是 PostHog 中记录第三方服务连接的system.*系统表是查询侧了解当前项目接入了哪些外部服务的唯一数据入口。本文以该表的完整字段定义为骨架结合仓库中 Integration 模型 的实现源码逐列讲解表结构、集成类型kinds、敏感配置加密机制与唯一约束并给出可直接套用的查询示例。读完你既能用 SQL 高效检索集成元数据也能理解这些连接在 PostHog 内部是如何被存储和管理的。一、认识 system.integrations第三方连接的数据底座PostHog 通过集成Integration把外部服务Slack、GitHub、Salesforce、各类广告平台等接入到产品分析流程中。system.integrations正是这些连接的按项目Team维度的元数据视图一条记录代表一个到外部服务的连接例如一个 Slack 工作区、一个 GitHub App 安装、一个 Salesforce 组织。在 querying-posthog-data 技能的数据模型参考体系中该表属于system.*系统实体表主要服务于以下场景确认某项目是否已接入某种外部服务如有没有配 Slack 集成结合kind与errors排查集成健康状态如广告平台 token 失效与 Hog 函数、批量导出、工作流Workflows等消费外部服务的实体做关联分析。底层上该表对应 Django 的 Integration 模型。需要强调的是该模型刻意不对外暴露加密凭证表内只保存非敏感元数据具体机制见下文第四节。二、表结构列定义与类型详解system.integrations的完整列定义如下与仓库文档一致ColumnTypeNullableDescriptionidintegerNOT NULL主键自动生成team_idintegerNOT NULL该集成所属的团队项目kindvarchar(32)NOT NULL集成类型标识见下文 Kinds 列表integration_idtextNULL外部系统中的标识如 Slack 工作区 ID、GitHub installation IDconfigjsonbNOT NULL非敏感、随 kind 而异的配置errorstextNOT NULL集成出问题时的错误信息无问题则为空字符串created_attimestamp with tzNOT NULL创建时间戳created_by_idintegerNULL创建者用户 ID对照源码可以确认各列的实际落点model.pyteam/team_id外键指向Teamon_deletemodels.CASCADE团队被删除时集成记录随之级联删除kindCharField(max_length32)对应IntegrationKind枚举值integration_idTextField(nullTrue, blankTrue)保存外部系统侧的唯一标识configJSONField(defaultdict)注释明确任何可以安全传给前端的配置Any config that COULD be passed to the frontendsensitive_configEncryptedJSONField——这是刻意不暴露的加密字段表中无对应列errorsTextField()无默认值非空字符串即表示存在错误created_atDateTimeField(auto_now_addTrue)创建时自动写入created_by外键指向Useron_deletemodels.SET_NULL用户被删除后该字段置空。三、Integration Kinds受支持的集成类型kind是集成表的分类键当前支持以下值slack、salesforce、hubspot、google-pubsub、google-cloud-storage、google-ads、google-sheets、google-cloud-service-account、snapchat、linkedin-ads、reddit-ads、tiktok-ads、bing-ads、intercom、email、linear、github、gitlab、meta-ads、twilio、clickup、vercel、databricks、azure-blob、firebase、jira、pinterest-ads从功能角度可以这样归类理解消息与协作slack、email、twilioCRM 与客服salesforce、hubspot、intercom代码托管与研发工具github、gitlab、linear、jira、clickup广告平台google-ads、meta-ads、snapchat、linkedin-ads、reddit-ads、tiktok-ads、bing-ads、pinterest-ads云存储 / 数据 / 消息google-pubsub、google-cloud-storage、google-cloud-service-account、google-sheets、databricks、azure-blob、firebase、vercel。值得注意这是查询system.integrations表时核心且常见的 kind 集合而源码中 IntegrationKind 枚举 的完整定义远不止这些还包含anthropic、apnsApple 推送、aws-redshift、aws-s3、s3-compatible、postgresql、snowflake、stripe、resend、google-analytics、google-calendar、youtube-analytics、customerio-*等。从源码结构可以推断枚举更全是因为其中一部分如数据仓库 / 存储类主要服务于批量导出等内部管道而slack-posthog-code已被注释明确标注为弃用Deprecated——运行时不再创建或读取该 kind。查询该表时应以文档列出的 27 个 kind 为权威集合。四、敏感配置隔离config 与加密的 sensitive_config这是该表设计中最重要的安全边界。文档明确指出sensitive_config加密的凭证、token被刻意不暴露在该表中。两者分工如下config非敏感的、kind 专属的结构化元数据如账户名account.name、工作区 ID、AWS 账户 ID、区域region等可以安全地渲染到前端sensitive_config存放access_token、refresh_token等真正的凭证使用 EncryptedJSONFieldFernet 对称加密落库仅在后端按需解密。源码对此提供了更细的实现证据模型通过field_access_control将kind、integration_id、config、sensitive_config均限制为 project 级 admin 权限可读model.pysensitive_config设置了ignore_decrypt_errorsTrue以兼容加密机制引入前写入的旧数据模型暴露了access_token与refresh_token两个只读属性均经由_decrypted_sensitive_value()读取model.py该方法会剥离可能的重复加密层read-then-save 可能造成双重加密并在所有密钥都无法解开时抛出UndecryptedIntegrationSecretError——该错误信息面向用户呈现We couldnt read the saved credentials for this connection. Reconnect the account to start syncing again.无法读取该连接的已保存凭证请重新连接账户以恢复同步并配套 Prometheus 计数器integration_sensitive_config_decrypt_recovery按kind、result统计恢复 / 不可读两类结果用于监控真实凭证是否正在丢失。因此在 SQL 侧你永远不会看到 token 等敏感数据——这正是查询该表可以放心用于审计与展示的前提。五、唯一约束与索引数据完整性的保障文档强调每个(team_id, kind, integration_id)组合是唯一的。源码用数据库层约束落实了这一点唯一约束posthog_integration_kind_id_unique字段组合为team、kind、integration_idmodel.py——同一项目内同一个外部服务标识不会出现重复连接记录辅助索引posthog_integration_kind_ext字段组合为kind、integration_id——为按类型 外部 ID 反查集成的典型查询例如按 GitHub installation ID 查找集成提供索引支撑。与之配套IntegrationManager 提供了first_github_for_team_installation、first_github_for_user_installation等便捷查询方法利用IntegrationQuerySet.for_github_installation_id()对config__installation_id同时匹配字符串与整数两种类型避免类型不一致导致的漏查。六、数据关系Team 与下游消费者文档给出两条关键关系集成归属于 Teamteam_id每条记录都挂在某个具体项目下配合唯一约束天然形成项目 → 外部服务的映射视图集成被 Hog 函数、批量导出Batch exports和工作流Workflows引用这三类实体在运行时需要真正调用外部服务集成记录提供的是连接元数据与后端持有的加密凭证。查询时如需哪些 Hog 函数 / 批量导出正在使用某个 Slack 或 GitHub 连接可以从对应实体的模型入手做反向关联。此外created_by_id源码中的created_by外键记录连接由哪位用户授权建立可用于审计谁接入了这个服务。七、集成是如何创建的OAuth 流与文件上传文档明确指出大多数集成是通过 OAuth 流程或文件上传创建的而非直接 API 调用。这解释了为什么该表本质上是事实的记录器而不是创建入口。源码佐证了这两条创建路径OAuth 流程oauth.py 中的OauthIntegration类定义了supported_kinds文档中的大部分 kind 都在其列并通过authorize_url()生成授权跳转地址、在回调后换取并保存 tokenrefresh_access_token()oauth.py负责 token 过期后的静默续期续期失败时会写入ERROR_TOKEN_REFRESH_FAILED定义于 common.py——这也解释了errors列为何可能非空文件上传如 Google 云服务账号google-cloud-service-account等类型通过上传 JSON 凭证文件建立连接AWS 类集成aws-s3等则保存 access key / role 等配置。每种 kind 的展示名由模型的display_name属性计算model.py例如 GitHub 取config.account.name、Pinterest 优先取config.business_name、Snowflake 拼接账户 认证方式未命中规则时回退到ID: integration_id。因此config的内容虽然随 kind 变化但总会包含用于前端展示的账户 / 工作区 / 业务名等信息。八、实战查询示例以下是基于表结构的可直接运行的查询示例假设通过posthog:execute-sql执行1. 查看某项目接入了哪些集成SELECT kind, integration_id, created_at, errors FROM system.integrations WHERE team_id 1 ORDER BY created_at DESC2. 按类型统计项目内的集成分布SELECT kind, COUNT(*) AS integration_count FROM system.integrations WHERE team_id 1 GROUP BY kind ORDER BY integration_count DESC3. 找出存在错误如 token 失效的集成SELECT id, kind, integration_id, errors FROM system.integrations WHERE team_id 1 AND errors 4. 查找某个 GitHub 连接的记录GitHub 以安装 ID 作为integration_idSELECT id, kind, config FROM system.integrations WHERE team_id 1 AND kind github AND integration_id 123456785. 最近 30 天内新建立的连接SELECT id, kind, integration_id, created_at, created_by_id FROM system.integrations WHERE team_id 1 AND created_at now() - INTERVAL 30 DAY ORDER BY created_at DESC九、查询注意事项小结sensitive_config不可见任何凭证、token 都不会出现在该表中查询结果天然适合展示与审计config结构随 kind 而异可能包含账户名、工作区 ID 等非机密元数据具体键名请结合对应 kind 的 provider 模块如 github.py、google_cloud.py确认唯一性语义(team_id, kind, integration_id)三元组唯一同一项目不会存在两条指向同一外部服务的同类连接errors为空字符串即健康非空表示该连接存在问题典型如 token 刷新失败排查集成类问题时可优先筛选此列创建入口不在 API连接通常经 OAuth 授权或文件上传建立直接向该表写入记录并不能获得可用凭证。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考