配置数据集¶

数据集是数据源中同类数据结构的集合。通过配置数据集，可以:

自定义数据的请求参数和返回字段，支持组件复用。
通过组合参数和计算字段简化组件配置，提高查询精度。
统一管理数据结构，提升维护效率。

备注

对于无默认结构的数据源（如 Static Data），必须创建数据集才能使用。对于有默认结构的数据源，创建数据集可覆盖默认配置，实现更灵活的数据处理。

本文面向应用开发人员，介绍如何配置和使用数据集。

前提条件¶

开始配置数据集前，确保：

已创建可用的数据源。更多信息，参见配置数据源。
明确业务场景的数据需求，例如需要的字段、查询条件等。

配置流程概览¶

配置数据集的整体流程如下：

新建数据集：选择数据源并填写数据集的基础信息。
配置请求参数（可选）：定义查询条件，Static Data 类型可跳过。
配置返回数据项：选择或调整返回字段。
调试与验证：模拟组件请求，预览返回结果。
使用数据集：验证无误后，在页面组件中使用数据集。

步骤 1：新建数据集¶

在数字孪生可视化中，进入 DTV 中心 > 数据源。
选择目标数据源对应的 数据集，进入数据集管理页面。
选择 新建数据集，根据数据源类型，在页面中配置以下内容：

类型	配置内容
Static Data 类型	输入数据集名称。在右侧选择下载模板，在 CSV 模板文件中输入静态数据后，选择导入上传文件。
其它数据源	输入数据集名称，并指定数据集关联的模型。

步骤 2：（可选）配置请求参数¶

请求参数用于定义数据查询条件，由数据源决定。如果原始参数过多，或不满足需求，可以在原始请求参数的基础上，通过筛选或组合的方式进行优化。

备注

Static Data 类型无需配置请求参数。

默认情况下，所有原始参数均已选中。你可以:

调整已选参数：缩小已选参数的范围或修改名称、描述。
添加组合参数：将多个参数组合成一个业务含义明确的条件。

调整已选参数 ¶

在数据集配置页面的 请求参数 标签页，查看左侧 可选参数 列表，默认全选所有原始参数。
如需减少冗余，可在 可选参数 列表中取消勾选不需要的参数。
如需自定义参数的展示名称和描述等，可选择参数对应的编辑按钮，配置以下内容：
- 展示名称：展示在组件配置页面的参数名称，支持国际化。
- 默认值：参数未指定时的默认取值。
- 描述：展示在组件配置页面的参数描述，用于在配置参数时提供帮助，支持国际化。

添加组合参数 ¶

组合参数适用于需要将多个参数值组合成一个查询条件的场景，避免多次选择，简化用户操作。例如：

假设你的数据源包含 3 个原始参数：province（省）、city（市）、district（区）。业务需求是用户在组件中只需选择一个“地区”参数，而不是分别选择省、市、区。你可以添加组合参数 Region（地区），并为每一枚举项配置省、市、区参数的值。用户在组件中只需选择“地区”，系统会自动将对应的省、市、区参数值传递给数据源。

备注

一旦原始参数被组合参数引用，该参数将无法单独作为原始参数配置或使用。若已有页面组件直接使用该原始参数，创建组合参数后，这些引用可能失效，需手动更新参数。

操作步骤如下：

在数据集配置页面的 请求参数 标签页，选择 添加组合参数。
在弹窗中定义组合参数的基本信息：
- 展示名称：展示在组件配置页面的参数名称，支持国际化。
- 参数 ID：参数的唯一标识符，在当前数据集中唯一。
- 描述：说明组合参数的用途。
选择底部的 添加枚举项，为组合参数添加枚举项，并配置枚举项的 展示名称、枚举项 ID 和描述。
如需为枚举项配置原始参数的值，可选择右侧的 添加原始参数，在表格中配置参数值。当用户在组合参数中选择一个枚举项时，表示请求多个原始参数的值的组合。

步骤 3：配置返回数据项¶

返回数据项定义了数据集输出的字段，决定组件可展示的数据范围。在配置返回数据项时，你可以选择：

方式一：使用默认结构：基于数据源提供的字段，进行筛选或扩展。
方式二：自定义结构：完全自定义输出结构，灵活满足业务需求。

方式一：使用默认结构 ¶

默认结构是数据源原始返回字段的集合，类似请求参数的处理方式，你可以：

筛选原始字段：只保留需要的字段，减少冗余。
添加计算字段：通过 JavaScript 脚本基于原始字段生成新字段。

例如，原始字段有 price（单价）和 quantity（销售量），业务需求是在可视化页面展示销售额。你可以新增计算字段 totalPrice（销售额），脚本为 return row.price * row.quantity，组件中即可直接展示 totalPrice。

操作步骤如下：

在 返回数据项 标签页，选择当前使用 默认结构。
在左侧 可选参数 列表中，默认勾选所有原始字段。如果不需要某些字段，取消勾选。
如需新增计算字段，可选择 添加计算字段，在弹窗中配置以下内容：
- 名称：计算字段在组件中展示的名称，支持国际化。
- ID：字段的唯一标识符，系统将自动添加 _DT_ 前缀。
- 数据类型：声明该字段返回的数据类型。
- 备注：字段用途说明，方便后续维护。
- JavaScript：定义如何计算该字段的脚本，长按 CTRL 可在脚本中引用原始字段。脚本返回的数据类型必须与声明的 数据类型 一致。

4. 配置后，选择弹窗右上角的确定，该字段会出现在可选参数列表中，默认勾选。

../_images/dataset_return_calculated_field.png

方式二：自定义结构 ¶

自定义结构适用于需要完全自定义返回数据格式的场景。与默认结构不同，自定义结构允许你重新组织数据源字段，并通过脚本定义输出结构，满足复杂业务需求。

例如，原始数据包含 province（省）、city（市）、price（单价）、quantity（销售量）、stock（库存量），业务需求是展示 region（地区）、totalPrice（销售额）和 status（库存状态）。你可以通过编写如下脚本，定义 region、totalPrice 和 status 3 个返回字段：

function(data, global, locale, log) {
    return data.map(function(item) {
        return {
            region: item.province + '-' + item.city,
            totalPrice: (item.price || 0) * (item.quantity || 0),
            status: item.stock > 0 ? '有货' : '缺货'
        };
    });
}

操作步骤如下:

在 返回数据项 标签页，选择当前使用 自定义结构。
选择右侧 从原始数据添加，声明需要在脚本中引用的原始字段。在上述示例中即 province、city、price、quantity、stock。待引用的字段列在 编写脚本关联数据项 列表中。
在脚本区域内编写 JavaScript 脚本，定义最终返回的字段及其值的计算逻辑。
在 脚本返回的数据结构 中，声明脚本返回的字段。可以选择 从原始数据添加 引用原始字段，或 添加自定义字段。脚本返回的字段需与引用的原始字段或自定义字段保持名称一致，且数据类型兼容。在上述示例中，需添加自定义字段 region、totalPrice 和 status。

步骤 4：调试与验证¶

为确保数据集配置正确，可使用调试功能模拟组件请求，验证返回结果。操作步骤如下：

在右上角选择调试。
在弹窗左侧的 需要展示的数据项 中，选择需要调试的返回字段。
在弹窗左侧继续配置请求参数的值。
配置后，选择上方的调试。
在弹窗右侧的 数据预览 中查看返回字段的值。
若返回异常，可在 链路追踪 中查看接口请求和响应的详细信息，快速获知详细日志。

步骤 5：使用数据集¶

配置完成后，选择页面右上角的保存，保存数据集配置。
参考配置组件数据，在仪表盘和单页应用页面的组件中使用数据集。
在 数据集管理 页面，可选择 关联页面，查看数据集关联的页面。

结果与后续操作¶

在目标数据源中，已创建一个数据集，并投入使用。如有需要，可在 数据集管理 页面，编辑或删除数据集。

备注

若删除的数据集已投入使用，相关页面的组件将无法获取数据，系统不会自动替换为默认数据源，需手动在组件配置中重新选择数据集。建议删除前先查看 关联页面，验证影响后再执行删除。