SQL数据表的使用

发布于 2026年10月14日

本文档介绍「SQL数据表」的功能与操作。SQL数据表允许您通过编写 SQL 语句，从已配置的来源数据库中抽取数据，生成可供电子表格、BI 分析、AI 小智等产品场景使用的数据表，并支持数据更新、参数化查询、数据预览、字段管理等一系列能力。

1. 功能总览介绍

SQL数据表是企业数据中的一种数据表类型。您可以将一段可执行的 SQL 查询语句固化为一张数据表，系统会按您设定的更新策略定时从来源数据库抽取数据，形成一份可重复使用的数据资产。

其主要能力包括：

能力	说明
数据抽取	通过 SQL 语句从来源数据库抽取数据，生成数据表
数据更新	支持「直连模式」与「抽取模式」，可按固定间隔或指定时间自动更新数据
参数化查询	支持在 SQL 中使用 `${参数名称}` 占位符，实现查询条件的动态化
数据预览	实时预览 SQL 执行结果与缓存数据
字段管理	查看与管理数据表字段，支持字段说明、AI 同义词等元信息
数据加工	基于已有字段做进一步的筛选、加工处理
数据操作	支持编辑、重命名、移动到、复制、删除等操作

SQL数据表的数据可在电子表格、BI 分析、AI 小智等产品模块中被引用使用，实现数据的统一管理与复用。

2. 新建SQL数据表

2.1 新建的配置流程

在「数据空间 → 数据中心 → 企业数据」页面中，点击右上角 新建数据集 按钮，在下拉菜单中选择 SQL数据表，即可打开「新建SQL数据表」配置弹窗。

新建 SQL 数据表需要配置以下内容：

配置项	是否必填	说明
数据表名	是	输入数据表的名称
来源数据库	是	选择需要连接的来源数据库（需先在系统中配置可用的数据库连接）
数据更新方式	是	可选「直连模式」或「抽取模式」
数据更新策略	是	设置自动更新的时间策略
SQL语句	是	编写用于取数的 SQL 查询语句
数据预览	-	点击「执行SQL」后，可预览 SQL 的执行结果

配置流程如下：

填写数据表名：为数据表起一个有意义的名称，便于后续识别与使用。
选择来源数据库：在「来源数据库」下拉框中选择要连接的数据库。若下拉为空，说明尚未配置可用的数据库源，需先在系统中完成数据库连接配置。
设置数据更新方式：
直连模式：查询时直接连接来源数据库实时取数；
抽取模式：将数据抽取并缓存到系统，按设定策略定时更新。
设置数据更新策略（抽取模式下可用）：
每 N 分钟自动抽取：按固定分钟间隔自动抽取数据；
每天 HH:mm：在每天的指定时间自动抽取。
编写 SQL 语句：在右侧「SQL语句」编辑区编写查询语句。
执行并预览：点击 执行SQL，在「数据预览」区查看取数结果，确认数据正确。
确认创建：点击确定完成创建。

说明：配置过程中如需放弃，可点击取消关闭弹窗。

2.2 SQL参数的配置与场景

SQL数据表支持在 SQL 语句中使用参数，实现查询条件的动态化。参数以 ${参数名称} 的形式写在 SQL 中，在实际使用数据时，由使用者为参数赋值。

参数格式

${参数名称}

在 SQL 语句中，使用 ${参数名称} 作为占位符。

参数类型

参数分为三种类型，其赋值时的处理方式不同：

参数类型	说明
单值	给参数赋值时，系统会根据字段的类型动态补充值进去；例如：数字类型直接填充，文本/日期类型结合数据库类型加引号后填充
多值	给参数赋值时，系统会根据字段的类型动态补充值进去；因为是多个值，系统补充进去的内容会自动加上单引号并用英文逗号隔离，即返回的是一组内容
原始值	给参数赋值时，赋什么值就原样填入 SQL 的对应位置，系统不做任何处理

参数示例（SQL Server 语法）

单值的使用：

and (t.accidname = ${合并报表-账套名称})

多值的使用：

select *
from kc_pinpaimingxi
where 1 = 1
and (机构编码 in (${机构编码}))

like 的使用：

where 1 = 1
and (机构编码 like concat('%', ${机构编码}, '%'))

常用场景实例：不输入查询参数时返回全部数据

为了让查询面板不输入任何条件时也能返回全部数据，可在 SQL 中为参数补充空值判断逻辑：

单值的使用（SQL Server 语法）：

and (t.accidname = ${合并报表-账套名称} or ${合并报表-账套名称} = '')

多值的使用（SQL Server 语法）：

select *
from kc_pinpaimingxi
where 1 = 1
and (机构编码 in (${机构编码}) or concat(${机构编码}, '', '') = '')

like 的使用（SQL Server 语法）：

where 1 = 1
and (机构编码 like concat('%', ${机构编码}, '%') or concat(${机构编码}, '', '') = '')

通过上述写法，当参数为空时条件恒成立，从而返回全部数据。

2.3 产品内SQL参数的使用

SQL数据表中配置的参数，默认值仅影响数据预览时的缓存值。当数据在实际使用场景中被重新赋值时，系统会将参数值回填给 SQL 后重新获取数据。

参数可在以下产品场景中通过查询面板进行赋值使用：

使用场景	说明	参考截图
电子表格	在电子表格的查询面板中配置与使用参数	电子表格参数配置01.png、电子表格参数使用02.png
BI 分析	在 BI 分析的查询面板中配置与使用参数	BI分析参数配置01.png、BI分析参数使用02.png
AI 小智	在 AI 小智中通过自然语言关联数据表并取数	AI小智使用01.png

配置查询条件时（如电子表格、BI 分析），通常包含以下设置项：

查询条件名称：为查询条件命名；
作用类型：选择「数据表中字段」或「数据表中参数」；
关联参数：关联 SQL 数据表中定义的参数（如「业务员」）；
参数值类型：单选 / 多选等；
查询样式：下拉单选、下拉多选等；
提示框内容：选择或自定义提示文案；
关联数据表 / 显示值 / 实际值：设置下拉选项的显示内容与实际取值；
默认值 / 必填：设置参数的默认值与是否必填。

使用时，在查询面板中为参数赋值后点击「查询」，系统会将参数值回填到 SQL 中执行取数。

AI 小智：可在对话中关联 SQL数据表，通过自然语言描述查询需求（如「王五的金额是多少？」），AI 小智会自动关联数据表参数进行取数并返回结果。

2.4 系统级参数说明

系统级参数，使用固定的参数形式，会自动获取与当前用户登录身份关联的参数值。在 SQL 语句中直接使用系统级参数即可，无需手动赋值。

系统级参数包括以下几种：

参数	说明	返回值查看位置
${SYS_组织编码}	获取当前用户的组织编码	用户中心上的【组织编码】
${SYS_用户名}	获取当前用户的用户名	用户中心上的【账号】
${SYS_真实姓名}	获取当前用户的真实姓名	用户中心上的【姓名】
${SYS_角色名}	获取当前用户的角色名	用户中心上的【角色】
${SYS_部门名称}	获取当前用户的部门名称	用户中心上的【部门】

使用示例（SQL Server 语法）：

where 1 = 1
and (t.accidname = ${SYS_用户名})
and (t.dept_name = ${SYS_部门名称})

说明：每个系统级参数返回的值，即对应用户在用户中心中该字段的取值。使用系统级参数，可让不同登录用户查询到各自身份对应的数据。

3. SQL数据表管理

在「企业数据」页面点击数据表名称（或左侧目录树中的数据表节点），进入数据表明细页面。页面顶部提供 导出、数据集详情、数据加工、编辑 等操作按钮，中部提供三个管理标签页：数据预览、数据字段、数据更新。

3.1 数据预览

「数据预览」标签页用于查看 SQL 数据表当前缓存的数据内容。

页面展示数据表的字段列与数据行，默认显示计算结果的前 100 行数据；
可通过 字段搜索 快速定位字段；
点击 导出Excel 可将当前预览数据导出为 Excel 文件；
底部展示数据更新时间、总缓存条数等信息，并支持分页浏览。

3.2 数据字段

「数据字段」标签页用于查看与管理数据表的字段信息。

列表展示每个字段的 序号、原始名称、显示名称、字段类型、字段类别、字段说明、AI同义词；
字段类型包括「数字」「字符串」等，字段类别通常为「数据列」；
点击编辑可修改字段的显示名称、字段说明、AI 同义词等元信息。

3.3 数据更新

「数据更新」标签页用于查看与管理数据表的更新方式与策略。

展示当前的更新模式（如「抽取模式」）与更新策略（如「每60分钟，自动抽取更新一次」）；
点击修改可调整数据更新方式与更新策略；
点击 立即更新 可立即执行一次数据抽取更新。

4. SQL数据表操作

在「企业数据」列表页中，可对 SQL数据表执行多种操作。列表行提供 编辑、删除 操作；勾选数据表（点击行前复选框）后，页面顶部会出现批量操作栏，提供 导出、移动到、复制、删除、清空 等操作。

4.1 编辑

点击数据表行的编辑按钮（或在明细页点击编辑），打开「编辑SQL数据表」弹窗。

编辑弹窗与新建弹窗结构一致，可修改：

数据表名
来源数据库
数据更新方式（直连 / 抽取）
数据更新策略（每 N 分钟 / 每天指定时间）
SQL语句（可点击 执行SQL 预览结果）

编辑界面支持 草稿 / 正式版本 两种状态：

修改内容会保存为草稿；
点击发布可将修改生效到正式版本；
如需放弃修改，可点击 放弃草稿 或取消。

4.2 数据加工

点击数据表明细页的 数据加工 按钮，进入「加工」工作区。

数据加工通过分步骤的方式对数据进行处理：

选字段：勾选需要保留的字段（支持全选、搜索）；
点击 新增加工步骤 可添加更多的加工步骤；
点击 刷新预览 查看当前步骤的处理结果；
完成后点击保存应用加工结果，点击返回退出加工。

4.3 重命名

重命名数据表可在「编辑SQL数据表」弹窗中完成：修改 数据表名 字段为新的名称，然后点击发布，数据表即以新名称保存。

4.4 移动到

勾选数据表后，在批量操作栏点击 移动到，在弹出的对话框中：

选择目标位置（文件夹 / 目录树节点）；
点击确定完成移动，点击取消放弃操作。

4.5 复制

勾选数据表后，在批量操作栏点击复制，系统会自动生成一份副本，副本名称形如「原名称_复制」，用于快速复制生成新的数据表。

4.6 删除

方式一（行内删除）：点击数据表行的删除按钮；

方式二（批量删除）：勾选数据表后，在批量操作栏点击删除。

删除时系统会弹出「是否确认删除？」确认框：

点击 确认删除 完成删除；
点击取消放弃删除。

注意：删除为不可恢复操作，请确认数据不再需要后再执行。

附：操作入口速查

操作	入口位置	说明
新建SQL数据表	企业数据 → 新建数据集 → SQL数据表	配置名称、来源库、更新策略、SQL
数据预览	数据表明细页 → 数据预览	查看缓存数据、导出Excel
数据字段	数据表明细页 → 数据字段	查看与编辑字段元信息
数据更新	数据表明细页 → 数据更新	修改策略、立即更新
编辑	列表行「编辑」/ 明细页「编辑」	修改配置并发布
数据加工	明细页「数据加工」	分步骤处理数据
重命名	编辑弹窗修改数据表名并发布	修改名称
移动到	勾选后批量操作栏「移动到」	移动数据表位置
复制	勾选后批量操作栏「复制」	生成副本
删除	列表行「删除」/ 勾选后批量操作栏「删除」	删除数据表（需确认）