数据源

数据源是 Crest 读取业务数据的入口。仪表盘、数据大屏和数据集都不会直接连接数据库或接口，而是通过数据源取得表结构、字段和数据预览。数据源配置是否规范，决定后续分析内容是否稳定。

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

这张图展示的是数据源的日常工作台。新建数据源前，先在左侧确认文件夹；维护数据源时，先在列表中确认名称、类型和最近更新时间；需要排查问题时，先打开右侧详情，再测试连接和预览表数据。

先认识页面

数据源页面分为左侧资源树、右侧数据源列表和详情区域。

选中一个数据源后，右侧会展示连接信息和维护动作。这里适合做日常检查：确认连接类型、最近更新时间、负责人和下游使用情况。

详情页重点看三处：第一是数据源名称和类型，确认没有选错环境；第二是连接状态和最近更新时间，判断连接是否仍可用；第三是下方表、字段和预览入口，保存后必须从这里验证数据源不是“只保存成功但不可查询”。

支持的数据源类型

Crest 支持常见数据库、分析型数据库、文件和接口数据源。创建前先确认数据的来源类型，再选择对应入口。

选择类型时不能只看数据库名称，还要确认网络、账号权限和数据更新方式。接口和文件虽然创建较快，但稳定性、字段变化和刷新机制需要额外关注。

类型选择页不是简单选择入口。数据库类数据源适合长期稳定的系统库或数仓；Excel/CSV 适合小规模补充表；API 适合只能通过接口开放的数据。选错类型会影响后续建模方式、刷新方式和权限维护。

可按数据形态选择入口：

示例说明：如果要做“项目交付看板”，项目、需求、工时这些数据来自研发系统数据库，就选数据库；季度目标来自人工维护的表格，就选 Excel/CSV；供应商 SLA 来自外部服务接口，就选 API。它们可以分别创建数据源，再在数据集里组合使用。

创建 MySQL 数据源

MySQL 是常见的数据源类型。其他数据库的字段名称会略有差异，但配置思路一致：先填写连接信息，再测试连接，最后保存并检查表字段。

表单中最关键的是“Crest 服务器是否能访问这个地址”。很多连接失败不是账号错误，而是将仅本地可访问的地址配置到服务器环境。填写完成后先测试连接，再保存；测试失败时不建议保存给后续人员排查。

这张表单可以按“名称、网络、身份、库表范围”四步填写：

1. 名称先写清楚用途，例如“项目交付库-生产只读”，便于后续用户判断是否为正确来源。
2. 主机和端口写 Crest 服务能访问的地址。部署在服务器上的 Crest 不能访问你电脑上的 localhost。
3. 用户名和密码使用只读账号。后续密码轮换时，要提前通知使用这个数据源的数据集负责人。
4. 数据库名或 Schema 要和 DBA 给出的范围一致。看不到表时，先排查这里和账号权限。

常用字段说明：

创建 Excel/CSV 数据源

Excel/CSV 适合补充小规模数据，例如预算表、目标值、门店映射、临时口径表。它不适合承载大规模明细数据，也不适合作为长期多人维护的核心数据源。

Excel 表单用于把一个文件变成可建模的数据源。上传前要先处理文件结构：第一行是字段名，下面每一行是数据，不要有合并单元格、说明行、空白列和人工汇总行。截图中的“上传文件”和字段识别区域，是后续数据集能否正常创建的关键。

示例：要把“季度目标表”放进 Crest，可以把文件整理成下面这种结构：

标题不应拆成两行，表格上方也不应放置“填报说明”。这些说明可以写进数据源备注或文档里，不要混入文件数据行。

上传前先整理文件：

1. 第一行必须是字段名。
2. 字段名不要重复，不要包含空白列。
3. 不使用合并单元格。
4. 日期列格式统一。
5. 数值列不要混入单位文字，例如“万元”“约 100”。
6. 删除空行、说明行、汇总行和隐藏列。
7. 文件名和数据源名称要能表达业务含义。

文件保存后，Crest 会把表头识别为字段。后续如果替换文件，字段名和字段类型要尽量保持一致，否则下游数据集和图表可能需要重新配置。

创建 API 数据源

API 数据源用于读取外部接口。它适合无法直接开放数据库、只提供服务接口的系统。配置 API 前，需要拿到接口文档，并确认鉴权、分页和返回结构。

API 表单先配置接口级信息，例如请求地址、请求方式、鉴权和公共参数。这里建议使用系统服务账号，不使用个人 Token；接口有过期时间或频率限制时，要在数据源说明里写清楚，方便后续维护。

填写 API 表单时，先用接口调试工具确认接口能返回数据，再回到 Crest 配置。Crest 里保存的不是“接口文档”，而是一个能被数据集读取的数据入口。请求方式、Header、Body、分页和超时只要有一项不对，后续数据集就可能空白或只读到第一页。

创建 API 数据源后，需要在数据源内添加 API 表。每个 API 表可以理解为一个可被数据集使用的接口结果。

添加 API 表时，重点是把接口返回结果整理成“表”。如果接口返回的是嵌套 JSON，要明确取哪一层作为数据行、哪些字段作为列。保存前使用测试请求检查返回结果，不应只凭接口文档配置。

例如接口返回：

{
  "code": 0,
  "data": {
    "records": [
      { "project": "Crest", "stage": "测试验证", "count": 12 }
    ]
  }
}

这时通常要把 data.records 作为数据行，把 project、stage、count 作为字段。不应把整个 data 对象作为一个字段，否则图表只能看到一段 JSON 文本，无法按项目或阶段统计。

v1.5.7 对 API 数据源的 JsonPath 解析做了修复。启用 JsonPath 后，系统会按指定节点解析行数据，而不是继续按完整响应推断结构。例如接口返回数据在 $data.dataList 下时，应把该路径配置为数据行位置，再从子节点中选择字段。启用 JsonPath 后，字段选择仍保持可编辑，便于补充字段名称、类型和业务说明。

常见 JsonPath 配置示例：

API 请求头中建议使用标准 Authorization 项承载 Token、Bearer Token 或 Basic Auth。不要把长期个人 Token 写入公开文档、截图或培训材料。

API 配置重点：

如果接口返回嵌套 JSON，先和接口负责人确认需要分析的字段。不应把整段原始 JSON 直接作为一个字段交给业务用户。

查看表和字段

数据源保存后，进入表管理区域检查库表是否完整。列表中通常可以看到表名、类型、注释等信息。

表列表用于确认 Crest 能看到哪些表或视图。正式项目建议优先使用业务视图或数仓宽表，减少直接读取原始业务表。看到表名后不要立刻拿去做图表，先打开表预览检查字段和样例数据。

打开目标表后，先检查字段，再做数据预览。

表预览用于做第一轮数据验收。预览阶段至少要检查字段类型、日期格式、金额单位、空值、乱码和样例行。如果源数据在预览阶段已经异常，后续数据集、图表和大屏都会受到影响。

保存后至少检查这些内容：

1. 目标表或视图是否能看到。
2. 字段名称、字段类型和注释是否完整。
3. 日期、金额、数量等关键字段是否识别正确。
4. 数据预览是否能返回结果。
5. 预览数据的时间范围是否符合预期。
6. 是否存在明显空值、乱码、权限屏蔽字段。

表能看到但预览失败，常见原因是账号没有查询权限、字段类型异常、视图 SQL 报错或数据量过大。先用同一账号在数据库客户端执行简单查询，再回到 Crest 排查。

日常维护

数据源不是创建一次就结束。密码轮换、库表变更、网络策略调整都会影响下游报表。

删除数据源前，至少确认：

1. 该数据源是否还被数据集使用。
2. 使用它的数据集是否还被图表、仪表盘或数据大屏使用。
3. 是否已有替代数据源。
4. 是否通知资源负责人。
5. 是否保留必要的配置和变更记录。

完整示例：创建一个项目交付数据源

下面用“项目交付库-只读”说明完整流程。示例里的名称、地址和字段都可以替换成自己的实际环境。

完成这个示例后，才进入数据集创建。数据源只证明 Crest 能读到数据，数据集才负责把字段整理成业务用户能使用的模型。

常见问题