企业官网建设流程全解析

DataHub 数据集使用情况与查询历史（Dataset Usage & Query History）实战指南

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub

数据集使用情况与查询历史（Dataset Usage & Query History）是 DataHub 中用于回答"谁在用这张表、最常执行的 SQL 是什么"的核心能力。本文以仓库内 dataset-usage-and-query-history.md 为骨架，结合 metadata-models 中的 Usage 相关数据模型、metadata-ingestion 中 Usage 摄取管线的真实配置项与 Snowflake/Redshift 等源的接入方式，完整讲解该功能的启用前置条件、界面交互、底层模型与常见问题。读完本文，你将掌握：如何判断某个数据源是否支持 Usage 统计、如何配置摄取、如何在 DataHub UI 中解读 Top Queries / Top Users / 列级使用统计，以及对应底层 aspect 与 GraphQL 类型。

功能概览：Usage 数据能回答什么问题

Dataset Usage & Query History 提供数据集维度的信息，核心包括：

• 最常引用的查询（Top Queries）：给出引用该数据集的 Top SQL 查询，帮助新人快速了解表最常见的读取方式；
• 最活跃用户（Top Users）：识别最了解该数据集的人，方便找到数据 Owner 或咨询对象；
• 总体指标：查询总数与去重用户数（distinct users）的整体概览；
• 列级使用统计（Column-level Usage）：部分数据源还会计算列级使用情况，帮助识别高频使用的字段（注意：Redshift Usage 目前尚不支持列级统计）。

对于支持 Usage 统计的数据源，你可以采集Dataset、Dashboard、Chart三类资源的 Usage 数据。

在数据模型层面，这套能力由一个**时序 aspect（timeseries aspect）**承载：DatasetUsageStatistics.pdl 以@Aspect = {"name": "datasetUsageStatistics", "type": "timeseries"}声明，意味着每次摄取都会按时间桶写入一条新的使用统计记录，DataHub 可以按时间窗口查询历史使用趋势。

数据模型：DatasetUsageStatistics 与时序桶（Bucket）

理解 Usage 功能前，先看底层字段定义。DatasetUsageStatistics记录（DatasetUsageStatistics.pdl）包含以下核心字段：

配套的两个子记录：

• DatasetUserUsageCounts.pdl：记录单个用户的使用次数（user: Urn+count: int），并带有userEmail: optional string字段——注释明确说明："如果设置了 user_email，摄取时会尝试将用户解析为对应的 corpuser URN"，这也是 UI 上能展示用户头像与名字的机制；
• DatasetFieldUsageCounts.pdl：fieldPath+count，用于列级使用热度。

此外，com.linkedin.usage命名空间下保留了一组更早期的聚合模型（UsageAggregation.pdl 与 UsageAggregationMetrics.pdl）。前者在 PDL 注释中已标注@deprecated = "Use DatasetUsageStatistics, or other UsageStatistics records, instead"，其字段（bucket、duration、resource、metrics）与UsageAggregationMetrics（uniqueUserCount、users、totalSqlQueries、topSqlQueries、fields）即为新模型的前身；目前 GraphQL 层仍在通过 Mapper 兼容消费这类聚合结果（见下文"后端支撑"）。从源码结构看，UsageAggregation被标记为废弃，新接入方应优先面向DatasetUsageStatistics系列模型。

前置条件与权限：先确认数据源能力

要摄取 Usage & Query History 数据，第一步是确认目标数据源是否支持该能力，以及如何开启。

DataHub 的每个 ingestion source 文档中都包含capabilities（能力）小节，列出了该源支持的功能（Metadata、Lineage、Usage、Profiling 等）。原文档中给出的判断方式是：

1. 打开对应数据源文档，查看 capabilities 小节；
2. 若该源支持 Usage，通常会给出独立的Usage-specific recipe（仅用于摄取 Usage 与 Query History 元数据的单独 recipe），并在 capabilities 摘要中注明；
3. 若该源有独立的usage prerequisites（使用前置条件）页面，务必阅读——Usage 摄取通常需要额外的数据库权限，而这些权限与普通元数据摄取不同。

在本仓库中，metadata-ingestion/docs/sources 目录下存放了全部数据源文档（如 Snowflake、Redshift、BigQuery、ClickHouse 等），每个源的 capability 说明与用法 recipe 都可以在那里找到。例如：

• Snowflake：在 snowflake_config.py 中，include_usage_stats默认值为True，其描述明确指出"启用后会采集 snowflake usage statistics，要求给角色授予相应的 grants"——这与原文档"务必检查 usage prerequisites"的提示完全对应；
• Redshift：需要独立的 usage recipe（capabilities 摘要中会特别标注），且 Redshift Usage 目前不支持列级统计。

实战建议：在配置摄取前，先到对应数据源文档的 capabilities 小节确认支持情况，并单独阅读其 usage prerequisites 页面，避免因权限不足导致 Usage 摄取静默失败。

摄取配置实操：BaseUsageConfig 常用参数

Usage 摄取管线在 Python 侧由 metadata-ingestion 实现，src/datahub/ingestion/source/usage/目录下集中了通用逻辑（如 usage_common.py）与各平台专用实现（如 clickhouse_usage.py、starburst_trino_usage.py）。

所有支持 Usage 的源共享一个基础配置类BaseUsageConfig（定义于 usage_common.py），常用参数如下：

值得注意的两个工程细节（来自 usage_common.py）：

1. top_n_queries与queries_character_limit之间存在校验关系：单条查询按最小 20 字符估算，top_n_queries不能超过queries_character_limit / 20，否则配置校验会直接报错（"top_n_queries is set to X but it can be maximum Y"）；
2. 摄取时会按**时间桶（bucket）**聚合：_make_usage_stat将同一时间窗口内的查询按用户、字段等维度计数，再生成DatasetUsageStatisticsClass对应的 MCP（Metadata Change Proposal），其中eventGranularity使用TimeWindowSizeClass(unit=bucket_duration, multiple=1)，这就是 UI 上按时间窗口展示历史使用趋势的数据来源。

以 Snowflake 为例，SnowflakeV2Config 中与 Usage 直接相关的开关包括：

• include_usage_stats（默认True）：采集 Snowflake usage statistics；
• use_queries_v2（默认True）：使用新一代 queries extractor 从 Snowflake 提取查询；
• include_queries（默认True）：生成与血缘边关联的 Query 实体（仅当use_queries_v2启用时生效）；
• include_query_usage_statistics（默认True）：生成查询热度统计（query popularity statistics，同样仅当use_queries_v2启用时生效）。

提示：部分源（如 Redshift）要求使用独立的 usage recipe摄取，不能与主 recipe 混跑；具体以该源文档的 capabilities 摘要为准。

在界面中使用：Queries 与 Stats 标签页

成功完成 Usage 摄取后，任何有 usage 数据的数据集，其详情页上的Queries 和 Stats 标签页会被启用。

Queries 标签页

在 Queries 标签页中，你可以看到引用该数据集的 Top 5 高频查询。这些查询来自topSqlQueries字段，按执行频次排序；对于 SQL 数据库（Snowflake、BigQuery、Redshift 等）而言，这一列表直接反映了数据集最常见的读取方式。配合上述include_queries/include_query_usage_statistics开关，还可以进一步生成独立的 Query 实体并关联血缘边，实现从查询反查数据集、从数据集反查查询的双向导航。

Stats 标签页

在 Stats 标签页中，你可以看到运行引用该数据集查询最多的 Top 5 用户。这里的数据来自userCounts数组（DatasetUserUsageCounts），并结合userEmail字段把邮箱解析成真实的 corpuser URN，因此界面上能展示出用户身份。该页面同时给出uniqueUserCount（去重用户数）与totalSqlQueries（查询总数）的概览。

列级使用统计

对于支持列级统计的数据源，数据集 Schema 页面会额外展示字段级使用热度（fieldCounts/DatasetFieldUsageCounts），帮助数据工程师识别高频访问列，从而优化分区键、索引或物化视图设计。注意：Redshift Usage 目前尚不支持列级统计（参见原文档说明）。

后端支撑：GraphQL 与 Mapper

Usage 数据在 UI 上的呈现依赖 GraphQL API。GraphQL 层位于 datahub-graphql-core，com.linkedin.datahub.graphql.types.usage包下的 Mapper 负责把底层 PDL/Java 模型转换为 GraphQL 输出类型：

• UsageAggregationMapper.java
• UsageAggregationMetricsMapper.java

这些 Mapper 对应 GraphQL 对象中的UsageAggregationMetrics、UserUsageCounts等类型（以及 Dashboard 侧对应的DashboardStatsSummary、DashboardUserUsageCounts），字段与 PDL 模型一一对应（uniqueUserCount、totalSqlQueries、topSqlQueries、users、fields等）。前端 datahub-web-react 中的数据集详情页、Dashboard 详情页正是通过这些 GraphQL 查询拉取 Usage 数据并渲染 Queries/Stats 标签页的。

如果你需要通过 API 二次消费 Usage 数据，可以直接查询这些 GraphQL 对象；底层 restli 服务则位于 usageStats，由 UsageStats.java 实现存取。

FAQ 与故障排查

为什么我的 Queries / Stats 标签页是置灰的（greyed out）？

这是最常见的 Usage 问题。置灰的原因只有两类：

1. 该数据集没有任何 usage 统计数据——即源端确实没有对该表的查询记录（或查询未被采集到）；
2. 之前从未运行过带 usage 提取的摄取任务——请检查 ingestion recipe 是否正确开启了 usage 相关开关（如 Snowflake 的include_usage_stats、Redshift 的独立 usage recipe），并确认执行用户/角色拥有 usage 统计所需的最小权限。

排查时可以依次确认：数据源 capabilities 是否支持 Usage → 是否使用了独立 usage recipe（如适用）→ 权限是否满足 prerequisites →top_n_queries/queries_character_limit配置是否合法 → 摄取日志中是否有 usage workunit 产出。

补充资源

• 数据源能力矩阵：查阅 metadata-ingestion/docs/sources 中各数据源文档的 capabilities 小节；
• 数据模型：见 metadata-models/src/main/pegasus/com/linkedin/dataset/DatasetUsageStatistics.pdl 及com.linkedin.usage命名空间下各 PDL；
• 摄取配置：见 usage_common.py 的BaseUsageConfig，以及各源的具体配置类（如 Snowflake 的 snowflake_config.py）；
• GraphQL API：datahub-graphql-core中types/usage包下的 Mapper 与 Usage 相关 GraphQL 对象定义；
• 入门视频：原文档推荐的 "DataHub 101: Data Profiling and Usage Stats 101" 可帮助快速建立对数据画像与使用统计的整体认知。

核心要点回顾：Usage & Query History 的完整链路是"数据源（Snowflake/Redshift/BigQuery 等）→ ingestion 摄取（BaseUsageConfig 聚合为时序 aspectdatasetUsageStatistics）→ GraphQL 暴露 → 前端 Queries/Stats 标签页"。启用前务必核对数据源 capabilities 与 usage prerequisites 权限，启用后即可在数据集详情页获得 Top 查询、Top 用户与列级热度三大视图。

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub