# 表与字段备注

为表和字段添加业务说明，帮助智能体理解数据含义。

表和字段备注用于补充业务含义，包括每条记录代表什么、指标如何计算，以及编码对应的含义。智能体据此选择相关字段和查询条件。

## 备注怎样改变查询结果

例如，人员表用 `sex` 保存性别，实际约定是 `1` 表示男性、`2` 表示女性。在字段备注里写清这个映射后，问“女性用户有多少”时，智能体就有依据使用 `sex = 2`，而不必猜编码的含义。这里的映射只是示例，应以你们的数据为准。

再如，基金评级列 `star` 存的不是数字，而是 `★★★★`、`★★★★★` 这样的星号文本。备注应写明“星级用星号文本保存”。问“四星及以上的基金”时，条件应该匹配实际文本：

```sql
-- 错误：把星号文本当成数字比较
WHERE star >= 4

-- 正确：匹配数据库里实际保存的值
WHERE star IN ('★★★★', '★★★★★')
```

好的备注不只是把字段名翻译成中文，还要交代单位、编码和实际存储方式，让业务问题能对应到正确的查询条件。

## 开始前

| 项目 | 要求                                      |
| -- | --------------------------------------- |
| 权限 | 项目负责人或项目管理员                             |
| 前置 | 数据源状态为正常可用（左侧栏出现库/表树）                   |
| 入口 | 左侧主导航 → 「更多」→ 「数据源」→ 点数据源卡片 → 左侧树里选中一张表 |

选中表后，右侧顶部是表名和备注两块，下面有「字段结构」「数据预览」两个页签，默认停在「字段结构」。

## 操作步骤

**写表描述**

表名右边是表描述的编辑框，标题是备注。

框里为空时，占位文字会说明这是数据库里的默认描述。输入内容后下方出现「保存」，点它写入；写入过程中按钮变成「保存中...」。

**写字段备注**

「字段结构」表有四列：列名、备注、语义类型、隐藏。

备注列显示当前生效的描述，最左边一个图标表示这条描述的来源：

| 图标    | 来源                 |
| ----- | ------------------ |
| 数据库图标 | origin，从数据库抓来的原始注释 |
| 机器人图标 | ai，AskTable 自动生成   |
| 笔图标   | human，人工写的         |

点字段行任意空白处展开详情面板，面板最下方是同一个备注的编辑框，占位文字会提示填写字段描述，或说明这是数据库里的默认描述。改完点「保存」。

备注列标题旁的信息图标提示要准确备注列的含义，以提高准确率。

**用 AI 优化润色**

编辑框右上角有一个星形图标按钮，鼠标悬停显示「自动优化字段描述」（表描述那里是「自动优化表描述」）。点它会调模型把当前内容改写一遍，结果直接回填到编辑框，不满意可以再改。

**设语义类型**

字段行里语义类型列显示当前值。展开详情面板后，同一个位置是语义类型下拉，按六组分类：

「关系」「数值」「地理」「文本」「时间」「实体」。

例如「数量」「货币」「收入」「毛利」在「数值」组，「城市」「国家」「邮编」在「地理」组，「主键」「外键」在「关系」组。选中即保存，不用点确认。

字段行标题旁的信息图标说明这是字段的分析语义（协议同 Metabase），人工设置的值不会被自动推断覆盖。

**批量改，走元数据导出导入**

字段多的时候不必逐个点。点顶栏「设置」，在「元数据」分区点「导出」拿到 JSON，在文本编辑器里批量改 `curr_desc`，再点「导入」把文件传回去。

导入会覆盖字段描述与可见性，训练数据是追加。文件型数据源要留意库名形如 `file_abc1`，那是系统生成的标识符，不是文件名。

## 关键约束

| 项目       | 值或默认                                   | 在哪里改                  |
| -------- | -------------------------------------- | --------------------- |
| 备注长度     | 上限 255 字；超出时计数标红、编辑框边框标红，「保存」不可点       | 编辑框本身                 |
| 备注优先级    | human（人工）> origin（数据库原始）> ai（自动生成）> 空串 | —                     |
| 语义类型覆盖规则 | 人工设置的值不会被自动推断覆盖；自动分类只填空值               | 字段详情面板的语义类型下拉         |
| 语义类型取值范围 | 「关系」「数值」「地理」「文本」「时间」「实体」六组             | —                     |
| 表描述为空    | 表列表里显示暂无表描述                            | —                     |
| 字段备注为空   | 编辑框占位显示数据库里的默认描述                       | —                     |
| 批量修改     | 覆盖描述与可见性，训练数据追加                        | 「设置」→ 「元数据」→「导出」/「导入」 |

## 出问题怎么判断

| 现象                | 判定条件                       | 处理                                                                  |
| ----------------- | -------------------------- | ------------------------------------------------------------------- |
| 数据库里明明有注释，备注列却是空的 | 备注列没有内容，编辑框里只是数据库默认描述的占位文字 | 数据库注释只作占位，没写进人工备注；补一条人工备注                                           |
| 保存点了没反应           | 字数超过 255，计数和边框标红           | 精简到 255 字以内再点「保存」                                                   |
| AI 还是挑错字段         | 展开工具调用，看到它用了别的列名           | 在备注里补单位、口径、枚举含义；必要时设语义类型                                            |
| 备注列图标不是笔          | 图标是数据库图标或机器人图标             | 该值来自数据库或自动生成；人工改一次后会变成笔图标                                           |
| 语义类型下拉里没有想要的值     | 展开下拉，六组里都找不到对应项            | 语义类型不是必填，改用备注写清这个字段的含义                                              |
| 批量导入后没生效          | 结果页提示导入完成但有项目未找到           | 导入文件里的 schema\_name / table\_name / field\_name 与目标数据源不一致，按缺失字段列表核对 |

## 下一步

- 让 AI 彻底忽略某些列，或把敏感值替换掉：[字段隐藏与脱敏](https://docs.asktable.com/data/hidden-fields)
- 用简称提问也能命中真实值：[AI 索引](https://docs.asktable.com/data/ai-search)
- 维护文件与训练集：[管理数据源、文件与训练集](https://docs.asktable.com/data/manage)
- 用一个真实问题验证效果：[对话](https://docs.asktable.com/conversation)