数据集

数据集是 Crest 的分析模型。数据源负责连接数据，数据集负责把数据整理成业务用户能理解、能拖拽分析的字段体系。后续图表、仪表盘和数据大屏都基于数据集取数。

入口：顶部菜单选择“数据准备”，进入“数据集”。

列表页用于管理数据模型。新建前选择保存目录；使用前确认数据集类型、最近编辑时间和创建人；删除、移动、重命名前先确认下游血缘。数据集不是临时查询，而是后续图表和大屏长期复用的模型。

先认识页面

数据集页面由资源树、数据集列表和详情预览组成。日常使用时，先在左侧文件夹定位资源，再在右侧查看数据集名称、类型、更新时间和操作入口。

选中数据集后，先查看数据预览。预览不只是确认“有没有数据”，还要检查日期范围、数值单位、维度取值和空值是否符合业务口径。

数据预览适合做“样例验收”。例如销售类数据要看日期、区域、订单数、金额；研发类数据要看阶段、项目、负责人、需求数和耗时。预览里出现空白、乱码或明显异常值时，先回到数据源或 SQL 处理，不应直接交给图表使用。

再切到结构页，检查字段是否被正确识别为维度或指标。字段分类错误会影响后续图表配置效率。

结构页决定业务用户如何使用字段。维度通常用于分组和筛选，指标用于求和、平均、计数。字段名应尽量使用业务语言，例如“需求数”“销售额”“负责人”，不建议保留 req_cnt、amt 这类数据库缩写。

支持哪些创建方式

Crest 的数据集可以从不同来源创建。首次建模建议先用单表或视图创建；需要统一口径、过滤和关联时，再使用 SQL 或多表建模。

选择方式时，可以按以下顺序判断：

1. 如果数据库里已经有宽表或视图，优先用“数据表/视图”。这是维护成本较低的方式。
2. 如果只需要筛选、改字段名、轻量聚合，可以用“自定义 SQL”。
3. 如果数据来自人工台账、目标值或映射表，先创建 Excel/CSV 数据源，再基于它建数据集。
4. 如果数据来自接口，先在 API 数据源中把接口配置成 API 表，再基于 API 表建数据集。
5. 如果要把事实表和维表组合起来，使用多表关联。确认主表粒度后再关联维表。
6. 如果两个来源不在同一个数据源中，才考虑跨源关联；正式页面使用前必须做性能和口径验证。

示例：做“需求流动与交付效率”大屏时，阶段快照适合用数据表或 SQL；人员目标值可能来自 Excel；供应商 SLA 可能来自 API；最终在数据集中整理成“日期、阶段、需求数、负责人、项目、耗时”等字段。

基于数据表创建数据集

表模式适合大多数入门场景。只要数据源里有可用表或视图，就可以把它拖入建模区，然后管理字段并保存。

这张图展示的是数据表模式的新建入口。左侧选数据源和表，中间是建模区，右侧是字段和预览。首次使用时，建议优先拖入一张已经整理好的视图，初始阶段不宜配置复杂多表关联。

编辑器中间是建模区，左侧是数据源表，右侧是字段和预览。单表模式下，建模区只需要放一张表或一个视图。

编辑器里最重要的是“建模区”和“字段区”。建模区决定数据来源，字段区决定后续图表可使用的字段。保存前要切换到预览，检查真实返回的数据，确认不只是完成了字段拖拽。

表模式保存前检查：

1. 表名或视图名是否选对。
2. 字段中文名是否清楚。
3. 维度和指标是否分组正确。
4. 日期字段是否能按时间排序。
5. 金额字段是否含税、是否折扣后、单位是否统一。
6. 预览数据是否能对上业务样例。

基于 SQL 创建数据集

SQL 模式适合需要先处理数据再交给图表使用的场景，例如合并多个字段、过滤无效记录、做轻量聚合、给字段起业务别名。

在编辑器中选择自定义 SQL 后，输入查询语句并运行。SQL 运行成功后，Crest 会根据返回结果识别字段。下图展示的是从表模式切到 SQL 模式后的入口：左侧仍然选择数据源，中间写 SQL，右侧查看字段和预览。

入口图展示的是从普通表模式切到 SQL 模式的位置。第一次使用时，先确认左侧选中了正确数据源，再打开 SQL 输入区。SQL 模式仍然依赖数据源权限；如果当前账号看不到数据源，SQL 编辑器也无法读取表。

SQL 编辑区不适合堆叠复杂业务逻辑。这里适合做轻量过滤、字段改名、简单聚合和多表查询。正式项目里，复杂且多人复用的口径建议放到数仓视图或公共模型中，数据集 SQL 只保留报表层必要逻辑。

这张图适合对照操作：左侧负责选表和查看字段，中间写 SQL，右侧或下方查看运行结果。编写 SQL 时不建议一次写入过多复杂逻辑，可先 select 少量字段并 limit 100，确认能运行后再补过滤、聚合和别名。

SQL 编辑窗口顶部有“运行、参数设置、系统变量、保存”等入口。写完 SQL 后先点运行，确认下方运行结果；需要让 SQL 接收外部条件时，再配置参数。未运行成功的 SQL 不应直接保存，否则后续图表无法获取字段。

SQL 创建建议按这个顺序做：

示例：

select
  order_date as `日期`,
  region_name as `区域`,
  city as `城市`,
  revenue as `销售额`
from v_daily_sales
limit 100

项目交付类示例可以写成：

select
  stat_date as `统计日期`,
  project_name as `项目`,
  stage_name as `需求阶段`,
  owner_name as `负责人`,
  req_count as `需求数`,
  avg_cycle_days as `平均周期天数`
from v_requirement_stage_daily
where stat_date >= date_sub(current_date, interval 90 day)
limit 500

这段 SQL 只是示例。真实项目应替换表名、字段名和日期范围；如果数据库不支持 date_sub 语法，要按对应数据库改写。重点是让返回字段直接服务图表：日期用于趋势，阶段用于分组，需求数用于统计，平均周期用于时效分析。

运行后先查看结果预览，确认字段、类型和示例数据都正确，再保存为数据集。

运行结果页要重点看三件事：返回列名是否是业务名称，字段类型是否能被识别，样例数据是否符合预期。字段名和类型确认清楚后，后续图表配置会更顺畅。

运行结果验收可以按以下内容检查：

SQL 编写建议：

如果 SQL 涉及参数、系统变量或动态条件，要在预览中测试不同值，不能只测试默认值。

多表和跨源建模

当一张表无法满足分析需求时，可以把事实表和维表组合成一个数据集。例如订单明细关联门店表、项目明细关联客户表。

多表建模仍然在表模式编辑器中完成。常见做法是先拖入事实表，再拖入维表，最后配置关联字段和关联方式。下面以“订单明细 + 门店维表”为例说明：订单明细负责金额和数量，门店维表负责区域、城市、门店等级等属性。

截图左上角的“单源/跨源”用于决定数据集是否可以选择多个数据源。单源适合大多数场景，性能和维护成本更可控；跨源适合多个系统之间做轻量关联。跨源建模前，先确认两个数据源的刷新时间、字段口径和数据量都能接受。

跨源并不是“能关联就应该关联”。如果数据量大、刷新频率高，建议先在数仓或数据库中加工成统一视图；如果只是把少量目标值、映射表或字典表补到主数据里，跨源会比较合适。

配置前先确认：

判断关联是否正确，可使用三个动作：

1. 先只拖主表，预览行数和指标合计。
2. 加入关联表后再次预览。
3. 对比核心指标是否被放大或明显变小。

如果指标被放大，优先检查关联字段是否唯一。一对多关联是常见原因。

多表建模操作顺序：

跨源建模要更谨慎。不同数据源的刷新时点、字段口径和性能差异都会影响结果。正式页面如果依赖跨源数据，建议在上线前记录清楚：每个源的来源、刷新频率、异常处理责任人。

字段管理

字段管理决定图表是否易用。字段不仅要“能查”，还要让业务用户理解并正确使用。

常见错误：

1. 金额字段被放到维度区，图表无法做求和。
2. 日期字段被识别为文本，趋势图顺序异常。
3. 文本 ID 被当成指标，出现无意义的求和。
4. 字段改名后，没有同步检查已有图表标题和筛选器。

计算字段

计算字段用于在已有字段基础上生成新字段。适合处理轻量公式，例如毛利、毛利率、客单价、完成率。

计算字段弹窗用于把已有字段组合成新字段。先输入字段名称，再写公式，最后保存并回到预览中抽样验证。公式字段如果要用于百分比，记得统一小数位和展示格式。

常见写法：

毛利 = 销售额 - 成本
毛利率 = 毛利 / 销售额
客单价 = 销售额 / 订单数
完成率 = 已完成数量 / 计划数量

配置建议：

1. 计算字段名称使用业务口径，不使用公式缩写。
2. 分母可能为 0 时要处理。
3. 百分比字段统一小数位和展示格式。
4. 金额字段明确是否含税、是否折扣后。
5. 保存后在预览中抽样核对。

计算字段适合轻量处理。复杂逻辑、跨多张表的计算和需要复用的公共口径，建议沉淀到上游数据仓库或视图。

分组字段

分组字段用于把明细取值整理成业务分组。例如把城市归到区域、把客户等级归到 A/B/C、把金额区间归到“低/中/高”。

分组字段弹窗用于把分散取值整理成业务分组。比如城市可以归到区域，金额可以分成区间，项目状态可以归并成“正常、风险、逾期”。配置完后一定检查“未分组值”，它过多通常说明规则不完整。

适合使用分组字段的场景：

分组字段保存后，要在预览里检查每个分组是否有数据，尤其是“其他”分组是否异常偏大。

预览、同步和变更

数据集保存后，不建议直接交给用户使用。应先完成一次完整检查。

保存后检查清单：

1. 数据预览能正常返回。
2. 字段结构清晰，维度和指标分类正确。
3. 关键指标抽样核对过。
4. 字段名称没有数据库缩写。
5. 计算字段和分组字段能返回正确结果。
6. 权限范围符合使用对象。
7. 如果开启缓存，同步时间和业务刷新频率一致。

源表字段变化后，数据集可能需要同步。常见变化包括新增字段、删除字段、字段改名、字段类型变化。同步后要检查下游图表是否仍能正常显示。

缓存、更新和定时任务

默认情况下，数据集可以采用直连方式读取源库。直连适合数据量较小、查询压力可控、源库稳定的场景。对于查询较重、源库不适合频繁访问，或需要固定刷新窗口的数据集，可以启用缓存，让 Crest 先把数据同步到缓存表，再由图表读取缓存结果。

v1.5.7 起，MySQL 数据源支持数据集缓存。基于 MySQL 创建的数据集可选择直连读取或缓存读取；仪表盘和数据大屏通过该数据集取数时，也可读取缓存结果。

缓存设置位于数据集编辑器左侧。图中“直连/缓存”决定查询路径，“增量/全量”决定每次更新的范围，“手动/定时”决定更新触发方式。设置完成后不能只保存，还要点击“立即更新”或等待定时任务执行，并检查状态。

这张图要按从上到下的顺序看：先决定直连还是缓存，再决定全量还是增量，最后决定手动还是定时。只设置“定时”但未完成首次同步时，仪表盘仍然无法读取缓存数据。

缓存区域常用配置如下：

全量更新

全量更新会重新拉取数据集范围内的数据。它适合数据量不大、字段结构经常变化，或没有可靠增量字段的数据集。

操作步骤：

全量更新配置简单，但数据量越大，执行时间和源库压力越高。正式环境建议避开业务高峰，例如设置在凌晨或数据仓库批处理完成之后。

点击“立即更新”时，系统会先保存当前数据集和缓存配置，再提交同步任务。修改字段、过滤条件、更新方式或定时配置后，不需要先单独保存一次再更新，但仍应在任务结束后检查预览结果。

增量更新

增量更新只拉取水位字段之后的新数据，并定期做全量校准。它适合订单、日志、需求流转、工单、流水等持续增长的数据。

高级设置用于控制缓存任务的稳定性。增量字段决定同步起点；全量刷新间隔用于定期校准缓存；超时时间防止任务长期挂起；更新后校验用于发现源端和缓存端差异。

高级设置不应随意跳过。增量字段选错时，常见问题不是任务失败，而是产生隐性漏数。比如需求状态会回写历史记录，只用创建时间做增量，就可能漏掉历史需求的状态变化；这种场景更适合用更新时间作为水位字段。

切换增量字段或更新方式时，系统会清理旧水位。下一次同步会按新配置重新计算水位，不会继续沿用旧字段的同步位置。变更前建议记录原字段、变更原因和首次同步结果，方便回溯。

增量更新要先选对水位字段。常见选择如下：

增量配置步骤：

定时更新

定时更新用于把数据集刷新节奏固定下来。它不等同于“越频繁越好”，刷新频率要和源数据产生频率、业务使用时间和系统承载能力匹配。

配置定时任务后，必须做两次检查：第一次看任务是否能按设置执行；第二次在下一个周期后回看缓存时间和页面数据是否更新。配置保存成功并不能证明任务长期稳定。

示例：项目周会每天上午 9 点查看交付大屏，可以把缓存定时设置在每天 8:30，前提是上游数仓在 8:00 前完成更新。如果上游 9:30 才更新，Crest 8:30 只能同步到旧数据，页面可展示但指标口径不准确。

定时配置建议写进数据集说明：

缓存上线检查

正式把缓存数据集交给仪表盘或大屏使用前，按以下清单检查：

1. 首次同步已成功，状态为缓存可用。
2. 数据预览能返回缓存结果。
3. 行数和源端样例一致，核心指标没有明显偏差。
4. 增量字段选择正确，历史补录不会漏数。
5. 定时频率和业务刷新时间一致。
6. 更新后校验已开启，异常时有人处理。
7. 下游图表已预览，不再读取旧字段或旧口径。

缓存状态中的“源数据与缓存一致”表示同步后的行数和校验结果符合当前配置；“数据一致性校验失败”表示源端与缓存端存在差异，需要查看任务日志、增量字段和源库变更。缓存失败时，先查看任务状态和最近一次日志，再检查源库连接、SQL、字段变化和任务超时。不建议反复点击“立即更新”，以免给源库带来额外压力。

删除前检查血缘

数据集通常被多个图表、仪表盘或数据大屏复用。删除前必须查看数据血缘，确认没有下游依赖，或已经完成替换。

处理顺序：

1. 在数据血缘中搜索数据集名称。
2. 查看下游图表、仪表盘和数据大屏。
3. 与资源负责人确认是否仍在使用。
4. 先替换或迁移下游图表。
5. 再删除数据集。

常见问题