> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据库元数据发现案例

> 使用 xpert_database 资源发现数据库结构并执行受控只读查询。

数据库资源适合让 Agent 理解 SQL DataSource 的结构，但不鼓励 Agent 直接自由写 SQL。UOSE 通过本体图谱和只读动作，把数据库探索变成可控流程。

## 适用场景

适合数据库发现的任务包括：

* 查找某个业务表。
* 查看表字段、类型和注释。
* 查看主键、外键、约束和索引。
* 预览少量数据。
* 解释一条 SELECT 查询计划。
* 执行行数受限的只读查询。

## 推荐流程

1. 注册 `xpert_database` resource。
2. 设置 catalog/table allowlist。
3. 开启 metadata enrichment。
4. 完成 full sync。
5. 在本体空间查找表或列。
6. 使用 `database.describe_table` 查看字段与约束。
7. 使用 `database.preview_rows` 预览少量数据。
8. 使用 `database.explain_query` 检查查询。
9. 使用 `database.query_select` 执行只读查询。

## 表结构理解

Agent 应先读取：

* table name。
* column name。
* data type。
* nullable。
* primary key。
* foreign key。
* index。
* comment。
* row count estimate。

这些信息能帮助 Agent 判断 join 条件、过滤字段和查询成本。

## 只读 SQL 边界

`database.query_select` 只允许单条只读语句。推荐：

* 设置明确 limit。
* 优先选择必要字段。
* 避免全表扫描大表。
* 复杂查询先 explain。
* 不执行 DDL、DML、CALL 或多语句。

如果用户要求更新、删除或建表，当前 v1 应明确拒绝或说明该能力仅在 ontology 中定义，运行时不执行。

## 元数据增强

开启 metadata enrichment 后，系统会按数据库方言补充：

* constraints。
* indexes。
* foreign keys。
* check。
* row count estimate。

如果某个方言不支持增强或增强 SQL 失败，同步不应整体失败。基础 metadata 仍会入图，失败原因会记录在 semantic context 或异常信息中。

## 安全建议

* 对生产数据库设置严格 allowlist。
* 限制 `maxQueryRows`。
* 不把敏感连接信息写入图谱。
* 对查询结果做最小展示。
* 对包含敏感列的表配置更严格策略。