oracle-jump-query-public/docs/操作示例.md

Oracle Jump Query 操作示例

这份文档用于说明如何向 Oracle Jump Query 提问，以及它会调用哪些只读能力完成查询。适合给业务分析、存储过程排查、表结构梳理、权限数据查询等场景使用。

基本原则

• 只执行只读操作：支持查询元数据和执行 SELECT，禁止 INSERT、UPDATE、DELETE、MERGE、TRUNCATE、DROP、ALTER 等写操作或结构变更。
• 优先给出明确对象：尽量提供 schema、表名、存储过程名、用户 ID、AD_TABLE.ID 等信息。
• 业务词先查字典：遇到“零售单”“采购入库”“调拨单”等业务词时，先从 AD_TABLE、AD_COLUMN、AD_REFBYTABLE 确认表和字段。
• 单据统计加状态条件：统计业务单据时，通常需要过滤 ISACTIVE = 'Y' AND STATUS = '2'。
• 明细表不靠猜：主表到明细表关系应通过 AD_REFBYTABLE 查询确认。
• 品小二中文条件：中文值直接写入 LIKE 可能因字符集转换返回 0 行，应改用 Oracle UNISTR Unicode 转义；其他 client 可按实际验证结果使用，UNISTR 也可作为跨环境复用时的 ASCII-safe 兜底。

多对话查询

你可以先说“查未芮”，随后直接说“看商品表结构”“查这个过程”。助手沿用当前对话客户，并在每条命令中自动携带 --client WEIRUI；另一个对话查其他客户不会影响本对话。下面未带客户参数的历史示例仍兼容默认客户，助手实际调用时应补上本对话编号。

python scripts/oracle_skill.py describe --client WEIRUI --json BOSNDS3 M_PRODUCT

常规查询无需先检查状态或切换共享默认客户；可信设备已审批时，失效登录由 CLI 自动恢复。

常见操作

1. 检查服务状态

用于确认中转服务和在线 Agent 是否可用。

用户可以这样问：

检查一下 Oracle Jump Query 服务是否正常，看看有哪些在线 Agent。

对应命令：

python scripts/oracle_skill.py health
python scripts/oracle_skill.py servers

2. 查询存储过程源码

用于查看某个存储过程的完整 PL/SQL 源码。

用户可以这样问：

帮我看一下 BOS.M_RETAIL_SUBMIT 的源码。

对应命令：

python scripts/oracle_skill.py source BOS M_RETAIL_SUBMIT

3. 完整分析存储过程

用于一次性查看源码、依赖对象、相关表结构和触发器。

用户可以这样问：

完整分析 BOS.M_RETAIL_SUBMIT，包括源码、依赖表、相关表结构和触发器。

对应命令：

python scripts/oracle_skill.py analyze BOS M_RETAIL_SUBMIT

适合排查：

• 提交流程做了哪些校验
• 存储过程更新了哪些业务表
• 是否调用了其他过程或函数
• 哪些触发器可能影响结果

4. 查询过程依赖

用于单独查看某个过程依赖的表、视图、函数或其他过程。

用户可以这样问：

查一下 BOS.M_RETAIL_SUBMIT 依赖了哪些表和过程。

对应命令：

python scripts/oracle_skill.py deps BOS M_RETAIL_SUBMIT

5. 查询表结构

用于查询字段、类型、索引、行数、注释等表结构信息。

用户可以这样问：

查一下 BOSNDS3.XCX_SO 的表结构。

对应命令：

python scripts/oracle_skill.py describe BOSNDS3 XCX_SO

6. 根据业务词找表

用于从中文业务名称反查系统中的业务表。

用户可以这样问：

帮我找“零售单”对应哪张表，以及提交过程是什么。

对应 SQL：

SELECT ID, NAME, TABLENAME, DESCRIPTION, PROC_SUBMIT
FROM AD_TABLE
WHERE NAME LIKE '%' || UNISTR('\96F6\552E') || '%'
   OR DESCRIPTION LIKE '%' || UNISTR('\96F6\552E') || '%';

对应命令：

python scripts/oracle_skill.py query "SELECT ID, NAME, TABLENAME, DESCRIPTION, PROC_SUBMIT FROM AD_TABLE WHERE NAME LIKE '%' || UNISTR('\96F6\552E') || '%' OR DESCRIPTION LIKE '%' || UNISTR('\96F6\552E') || '%'"

7. 查询字段业务含义

用于确认字段显示名、业务描述和字段类型。

用户可以这样问：

查一下 M_RETAILITEM 每个字段的业务含义。

对应 SQL：

SELECT DBNAME, NAME, DESCRIPTION, COLTYPE
FROM AD_COLUMN
WHERE AD_TABLE_ID = (
    SELECT ID FROM AD_TABLE WHERE NAME = 'M_RETAILITEM'
)
ORDER BY ORDERNO;

对应命令：

python scripts/oracle_skill.py query "SELECT DBNAME, NAME, DESCRIPTION, COLTYPE FROM AD_COLUMN WHERE AD_TABLE_ID = (SELECT ID FROM AD_TABLE WHERE NAME = 'M_RETAILITEM') ORDER BY ORDERNO"

8. 查询主表和明细表关系

用于确认主表有哪些明细表，以及明细表通过哪个字段关联主表。

用户可以这样问：

查一下 M_RETAIL 有哪些明细表，外键字段是什么。

对应 SQL：

SELECT t1.NAME AS MAIN_TABLE,
       t2.NAME AS DETAIL_TABLE,
       c.DBNAME AS REF_COLUMN,
       r.ASSOCTYPE
FROM AD_REFBYTABLE r
LEFT JOIN AD_TABLE t1 ON r.AD_TABLE_ID = t1.ID
LEFT JOIN AD_TABLE t2 ON r.AD_REFBY_TABLE_ID = t2.ID
LEFT JOIN AD_COLUMN c ON r.AD_REFBY_COLUMN_ID = c.ID
WHERE t1.NAME = 'M_RETAIL';

对应命令：

python scripts/oracle_skill.py query "SELECT t1.NAME AS MAIN_TABLE, t2.NAME AS DETAIL_TABLE, c.DBNAME AS REF_COLUMN, r.ASSOCTYPE FROM AD_REFBYTABLE r LEFT JOIN AD_TABLE t1 ON r.AD_TABLE_ID = t1.ID LEFT JOIN AD_TABLE t2 ON r.AD_REFBY_TABLE_ID = t2.ID LEFT JOIN AD_COLUMN c ON r.AD_REFBY_COLUMN_ID = c.ID WHERE t1.NAME = 'M_RETAIL'"

9. 查询有效已提交单据

用于统计或分析正式业务数据。单据类数据通常要排除草稿、审批中、作废或删除记录。

用户可以这样问：

查询 2026-05-01 的有效已提交零售单，返回前 10 条。

对应 SQL：

SELECT *
FROM M_RETAIL
WHERE ISACTIVE = 'Y'
  AND STATUS = '2'
  AND BILLDATE = 20260501
  AND ROWNUM <= 10;

对应命令：

python scripts/oracle_skill.py query "SELECT * FROM M_RETAIL WHERE ISACTIVE = 'Y' AND STATUS = '2' AND BILLDATE = 20260501 AND ROWNUM <= 10"

10. 查询用户数据权限

用于查看某个用户对某张业务表的数据范围。

用户可以这样问：

查一下用户 940 对 M_OTHER_INOUT 的数据权限，表 ID 是 12983。

对应命令：

python scripts/oracle_skill.py perm 940 12983

返回结果通常包含：

• perm_sql：权限过滤条件
• has_restriction：是否存在权限限制
• 空权限条件：通常表示全权限

11. 执行带权限过滤的查询

用于按用户权限自动拼接过滤条件后查询数据。

用户可以这样问：

用用户 940 的权限查询 M_OTHER_INOUT，表 ID 是 12983，只看 2026-05-01 的数据。

对应命令：

python scripts/oracle_skill.py qperm 940 12983 "SELECT * FROM M_OTHER_INOUT WHERE BILLDATE = 20260501"

系统会自动把 get_userspermsql 返回的权限条件追加到查询中。

12. 查询表空间使用情况

用于查看数据库表空间的整体使用状况，包括总大小、已用、剩余、使用率、是否自动拓展等信息。

自动降级策略

脚本按优先级自动尝试 5 种方式，无需手动切换：

优先级	方式	条件
1️⃣	直查 DBA_DATA_FILES + DBA_FREE_SPACE	用户有 SELECT_CATALOG_ROLE
2️⃣	DBA 专用函数 sys.get_tablespace_usage()	DBA 已执行 CREATE FUNCTION
3️⃣	查询 DBA 授权 VIEW HENLO_TS_USAGE	DBA 已执行授权 SQL
4️⃣	查询 SYS.HENLO_TS_USAGE（带 sys.前缀）	DBA 以 SYS 身份创建的视图
5️⃣	查 USER_FREE_SPACE	始终可用（仅剩余空间）

经验：DBA 以 SYS 身份登录创建的 VIEW 归属到 SYS schema，需用 sys. 前缀才能查到。脚本会自动先试无前缀，再试 sys. 前缀。

无权限时的处理流程

当用户无 DBA 系统视图权限时，脚本会自动输出以下内容：

1. 尝试 DBA 专用函数（如果有）
2. 尝试 DBA 授权 VIEW（无前缀 → sys.前缀）
3. 如果前两步都不存在，输出给 DBA 的授权 SQL
4. 回退到 USER_FREE_SPACE 查询，显示各表空间的剩余空间

HENLO 环境实际输出（授权前）

📊 表空间使用情况（用户视图 -- 无DBA权限，仅显示名称和剩余空间）：
| 表空间名称 | 剩余MB |
| --- | --- |
| BOSNDS3 | 518.81 |
| BOSNDS3_IDX | 17.56 |
| RETAILNDS3 | 9.31 |
| RETAILNDS3_IDX | 19 |
| SYSAUX | 329.94 |
| SYSTEM | 7.19 |
| ULOG | 39 |
| UNDOTBS1 | 474.38 |
| USERS | 2.31 |

DBA 授权后的实际完整输出

DBA 以 SYS 执行授权 SQL 后，再次查询自动获得完整信息（脚本自动识别 SYS.HENLO_TS_USAGE）：

📊 表空间使用情况一览（通过 DBA 授权 VIEW）：
| 表空间名称 | 总大小MB | 已用MB | 剩余MB | 使用率% | 自动拓展 | 最大可拓展MB | 最大使用率% |
| --- | --- | --- | --- | --- | --- | --- | --- |
| SYSTEM | 1230 | 1222.8 | 7.2 | 99.4 | YES | 32768 | 3.7 |
| SYSAUX | 6620 | 6290.1 | 329.9 | 95 | YES | 32768 | 19.2 |
| UNDOTBS1 | 505 | 30.6 | 474.4 | 6.1 | YES | 32768 | 0.1 |
| BOSNDS3_IDX | 20 | 2.4 | 17.6 | 12.2 | YES | 32768 | 0 |
| ULOG | 40 | 1 | 39 | 2.5 | YES | 32768 | 0 |
| RETAILNDS3_IDX | 20 | 1 | 19 | 5 | YES | 32768 | 0 |
| USERS | 5 | 2.7 | 2.3 | 53.8 | YES | 32768 | 0 |
| BOSNDS3 | 10690 | 10171.2 | 518.8 | 95.1 | YES | 32768 | 31 |
| RETAILNDS3 | 110 | 100.7 | 9.3 | 91.5 | YES | 32768 | 0.3 |

**共 9 行**

⚠️ 脚本自动检测到 3 个表空间使用率 ≥ 95% 并输出告警。

字段解释

字段	说明
表空间名称	Oracle 表空间名称
总大小MB	当前数据文件总大小（MB）
已用MB	已分配使用的空间（MB）
剩余MB	剩余可用空间（MB）
使用率%	（已用 / 总大小）× 100%
自动拓展	YES=数据文件自动扩展，NO=固定大小
最大可拓展MB	自动扩展后能达到的最大值（MB）；不自动扩展时=当前大小
最大使用率%	（已用 / 最大可拓展）× 100%，反映最终可用的百分比

阈值参考

使用率	状态	建议
< 80%	✅ 正常	无需处理
80% ~ 95%	🔶 关注	评估未来增长，制定扩容计划
≥ 95%	⚠️ 紧急	尽快扩容或清理空间！

智能告警规则：脚本逐行解析表空间数据，自动判断衡量指标。

• 自动拓展=YES：按 最大使用率%（已用/最大可拓展）判断
• 自动拓展=NO：按当前 使用率%（已用/当前总大小）判断

例如 SYSTEM 使用率 99.4% 但最大使用率仅 3.7%，说明只是当前数据文件写满而非存储瓶颈，自动扩展后即可释放。

给 DBA 的授权说明

当无 DBA 权限时，脚本会自动输出以下信息，请交给 DBA 执行：

-- 以 SYS 身份执行
CREATE OR REPLACE VIEW SYS.HENLO_TS_USAGE AS
SELECT
    df.tablespace_name AS "表空间名称",
    ROUND(df.total_bytes / 1048576, 1) AS "总大小MB",
    ROUND((df.total_bytes - NVL(fs.free_bytes, 0)) / 1048576, 1) AS "已用MB",
    ROUND(NVL(fs.free_bytes, 0) / 1048576, 1) AS "剩余MB",
    ROUND((df.total_bytes - NVL(fs.free_bytes, 0)) / df.total_bytes * 100, 1) AS "使用率%",
    df.autoextensible AS "自动拓展",
    ROUND(df.max_bytes / 1048576, 1) AS "最大可拓展MB",
    ROUND((df.total_bytes - NVL(fs.free_bytes, 0)) / NULLIF(df.max_bytes, 0) * 100, 1) AS "最大使用率%"
FROM (
    SELECT
        tablespace_name,
        SUM(bytes) AS total_bytes,
        SUM(CASE WHEN autoextensible = 'YES' THEN maxbytes ELSE bytes END) AS max_bytes,
        MAX(CASE WHEN autoextensible = 'YES' THEN 'YES' ELSE 'NO' END) AS autoextensible
    FROM dba_data_files
    GROUP BY tablespace_name
) df
LEFT JOIN (
    SELECT tablespace_name, SUM(bytes) AS free_bytes
    FROM dba_free_space
    GROUP BY tablespace_name
) fs ON df.tablespace_name = fs.tablespace_name
ORDER BY 6 DESC;

GRANT SELECT ON SYS.HENLO_TS_USAGE TO bosnds3;

为什么加 SYS. 前缀：DBA 以 SYS 身份执行 CREATE VIEW 时，视图创建在 SYS schema 下。GRANT 也必须指定 SYS. 前缀，否则普通用户无法找到。脚本会自动处理带前缀和不带前缀两种情况。

原理：Oracle 视图默认使用定义者权限（DEFINER），以创建者的 DBA 身份执行。普通用户仅需 SELECT 权限，比直接授予 SELECT_CATALOG_ROLE 更安全。

给 AI 的指令

当用户通过 AI 查询表空间时，流程：

1. 自动调用 python oracle_skill.py tablespace
2. 脚本自动尝试 5 层降级
3. 如果全部权限方案不可用，输出授权 SQL + 回退到剩余空间查询
4. 将授权 SQL 发送给用户，让其联系 DBA 执行
5. DBA 执行后，再次查询即可自动使用完整信息
6. 注意：DBA 以 SYS 执行时，VIEW 会创建在 SYS schema 下，GRANT 也需带 SYS. 前缀

用户可以这样问：

帮我查一下数据库表空间使用情况
查看表空间
表空间够不够用

对应命令：

python scripts/oracle_skill.py tablespace
# 或
python scripts/oracle_skill.py tablespaces

13. 生成 NL2SQL 字典

用于为自然语言转 SQL 准备 schema 字典。

用户可以这样问：

给 BOSNDS3 的 RETAIL 业务域生成 NL2SQL schema 字典。

对应命令：

python scripts/oracle_skill.py nl2sql BOSNDS3 RETAIL

典型完整流程

流程一：分析一个业务提交流程

用户可以这样问：

帮我分析零售单提交逻辑，从业务表、提交过程、依赖表到关键校验都梳理出来。

推荐执行顺序：

1. 从 AD_TABLE 查询“零售单”对应主表和 PROC_SUBMIT。
2. 使用 source 或 analyze 查询提交过程源码。
3. 使用 deps 查询依赖对象。
4. 使用 describe 查询关键表结构。
5. 结合源码解释提交校验、状态变更、库存或财务影响。

流程二：构造一条可靠统计 SQL

用户可以这样问：

我要统计 2026 年 5 月零售销售额，帮我确认主表、明细表、金额字段并生成 SQL。

推荐执行顺序：

1. 查 AD_TABLE，确认零售主表。
2. 查 AD_REFBYTABLE，确认零售明细表。
3. 查 AD_COLUMN，确认数量、金额、日期、门店字段。
4. 生成 SQL 时加入 ISACTIVE = 'Y' AND STATUS = '2'。
5. 如需按用户权限过滤，使用 qperm。

示例 SQL：

SELECT r.C_STORE_ID,
       SUM(i.TOT_AMT_ACTUAL) AS SALE_AMOUNT
FROM M_RETAIL r
JOIN M_RETAILITEM i ON i.M_RETAIL_ID = r.ID
WHERE r.ISACTIVE = 'Y'
  AND r.STATUS = '2'
  AND r.BILLDATE BETWEEN 20260501 AND 20260531
GROUP BY r.C_STORE_ID;

排查建议

• agent not found：先执行 servers，确认 Agent 是否在线。
• 查询超时：缩小查询范围，或对 analyze 类命令增加超时时间。
• 查不到业务表：先扩大 AD_TABLE 的关键字范围，再结合 DESCRIPTION 判断。
• 字段含义不明确：优先查 AD_COLUMN.DESCRIPTION，不要只凭字段名猜。
• 统计结果异常：检查是否遗漏 ISACTIVE、STATUS、日期范围、门店权限等条件。