配置字段语义

字段语义配置用于告诉 Analytics Agent：表里的每个字段在业务上代表什么、适合怎么被问答系统使用、能否作为筛选条件或分组维度、是否应该参与索引和分析。

自然语言问答并不是只依赖字段名生成 SQL。字段别名、字段描述、字段类型、字段用途、隐藏状态、虚拟列和表关系都会影响系统理解问题、选择字段、生成 SQL 和解释结果。

为什么字段语义配置很重要

在分析域中添加表后，系统会自动读取表结构，但数据库字段名通常是面向开发或建模的，不一定能被业务用户直接理解。

例如：

字段名用户可能的说法如果不配置可能出现的问题
active_subscription
active_subscription
活跃账户、有效订阅、当前活动用户系统可能不知道“活跃”应该用哪个字段判断。
plan
plan
套餐、版本、计划类型用户说“按套餐”时，系统可能无法稳定映射到 
plan
plan
。
seats
seats
席位数、座席数、账号数量系统可能把它当维度，而不是度量值。
created_at
created_at
创建时间、开户时间、注册时间系统可能不知道时间语义和默认分析粒度。

实际操作中，分析域健康度会检查字段描述缺失问题。如果表字段缺少描述，健康度会提示异常，说明字段语义不是可选装饰，而是会影响问答准确性的基础配置。

用字段语义消除字段歧义

大模型在生成 SQL 时，经常需要从多个候选字段中选择一个字段。如果一个表内存在相似字段，或者多个表里存在同名、近义字段，模型可能因为歧义而误选字段。

字段语义配置的一个重要作用，就是降低这种误选概率。

常见歧义包括：

歧义类型示例可能的误选
同表相似字段
created_at
created_at
、
trial_ends_at
trial_ends_at
、
canceled_at
canceled_at
用户说“时间”时，系统不知道该用创建时间、试用结束时间还是取消时间。
同表状态字段
active_subscription
active_subscription
、
trial_converted
trial_converted
、
legacy_plan
legacy_plan
用户说“活跃用户”时，系统可能误用试用转化或历史套餐字段。
多表同名字段多张表都有 
id
id
、
name
name
、
created_at
created_at
多表查询时可能选错表的字段。
业务词一词多义“用户数”可能指账户数、客户数、订阅数系统可能使用不符合业务口径的计数字段。
技术字段和业务字段混杂
source
source
、
channel
channel
、
utm_source
utm_source
用户说“渠道”时，系统可能不知道使用哪个字段。

因此，字段语义配置不只是“给字段加注释”，更是在告诉系统：当用户使用某个业务词时，应该优先选择哪个字段，不应该选择哪个字段。

建议使用以下方式消除歧义：

配置方式作用
字段别名把业务用户常用说法绑定到正确字段，例如把“套餐”绑定到 
plan
plan
。
字段描述说明字段的业务含义和适用场景，例如 
active_subscription
active_subscription
才表示当前活跃订阅。
字段用途标明字段适合做维度、过滤还是度量，减少把度量字段误当维度。
隐藏字段对不应被问答使用的技术字段或干扰字段进行隐藏。
知识配置对复杂业务口径做明确说明，例如“活跃账户数指 active_subscription = TRUE 的账户数量”。
表关系配置在多表场景中明确字段来自哪张表、如何关联，减少跨表误选。

例如，账户表中同时存在 

active_subscription
active_subscription
、
trial_converted
trial_converted
、
canceled_at
canceled_at
。如果用户问“活跃账户数”，推荐配置如下：

字段推荐语义
active_subscription
active_subscription
别名配置为“活跃订阅、是否活跃、有效订阅”；描述说明 TRUE 表示当前订阅有效，可用于统计活跃账户。
trial_converted
trial_converted
描述说明它表示试用是否转付费，不等同于当前活跃账户。
canceled_at
canceled_at
描述说明它表示取消时间，不能单独作为活跃账户判断条件。

这样，当用户说“活跃账户”时，系统更容易选择 

active_subscription
active_subscription
，而不是误用 
trial_converted
trial_converted
或 
canceled_at
canceled_at
。

字段语义的典型使用场景

字段语义配置的价值不只体现在字段说明上，更体现在实际问答和分析链路中。下面这些场景都依赖字段语义来提高准确性和可控性。

使用场景字段语义的价值示例
把业务词映射到技术字段让用户不用知道真实字段名，也能问出正确结果。用户说“套餐”，系统映射到 
plan
plan
；用户说“获客渠道”，系统映射到 
source
source
。
消除相似字段歧义帮助系统在多个候选字段中选择正确字段。“活跃账户”应优先使用 
active_subscription
active_subscription
，而不是 
trial_converted
trial_converted
或 
canceled_at
canceled_at
。
指定字段在 SQL 中的角色判断字段应出现在 
WHERE
WHERE
、
GROUP BY
GROUP BY
、聚合函数还是 SELECT 明细中。
plan
plan
适合分组和过滤；
seats
seats
适合求和；
created_at
created_at
适合时间过滤。
支持答案构建器参数决定哪些字段能被 
${filters}
${filters}
和 
${dims}
${dims}
使用。		用户说“只看 Google 来源”时，
source
source
需要可作为过滤字段；用户说“按 Plan”时，
plan
plan
需要可作为维度。
提高自动生成指标质量帮助系统判断字段是否适合生成 COUNT、SUM、AVG、MAX、MIN 等指标。
seats
seats
配成连续度量后，更适合生成总席位、平均席位等指标。
改善自然语言解释让答案不仅有数字，还能解释口径。字段描述写清 
active_subscription = TRUE
active_subscription = TRUE
后，答案可以说明“基于当前有活跃订阅的账户统计”。
降低高基数字段误用避免系统把 ID、邮箱、姓名等字段作为默认分组维度。不建议默认按 
email
email
或 
account_name
account_name
分组分析账户健康。
控制敏感字段可见性通过隐藏字段减少敏感列在问答中被使用或展示。手机号、邮箱、身份证、内部成本字段可以隐藏。
支持虚拟列成为业务字段让派生表达式拥有可理解的业务语义。
concat(first_name, ' ', last_name)
concat(first_name, ' ', last_name)
配置为“客户姓名”后，可被用户自然提问。
支持多表问答帮助系统判断字段归属和关联关系。多张表都有 
created_at
created_at
时，字段描述应区分订单创建时间、客户注册时间、支付时间。
支撑健康度和上线检查字段缺描述、用途不清会影响分析域健康度。健康度提示字段描述缺失时，应优先补充核心字段。
降低用户提问门槛让用户用业务语言提问，而不是记字段名。“按套餐看活跃率”“只看 Google 来源”“最近一个月新增账户数”。

从使用效果看，字段语义配置越充分，Analytics Agent 越容易完成三件事：

  1. 理解用户说的业务词。
  2. 选择正确字段和 SQL 角色。
  3. 用符合业务口径的方式解释结果。

配置入口

进入字段配置的一般路径：

  1. 进入 管理 -> 分析域管理。
  2. 打开目标分析域。
  3. 进入 数据 页签。
  4. 点击 表。
  5. 点击表展示名，进入表详情页。
  6. 在 表结构 页签中配置字段。

表详情通常包含三个页签：

页签作用
表结构查看和配置字段语义、索引、隐藏、字段类型、字段用途、表关系等。
数据预览查看样例数据，帮助判断字段真实取值和业务含义。
统计分析查看字段 COUNT、NULL VALUE、DISTINCT、MIN、MAX、AVERAGE、SUM 等统计信息。

建议先看 数据预览 和 统计分析，再配置字段语义。不要只根据字段名猜业务含义。

字段配置项说明

表结构中常见字段配置如下：

配置项作用对问答的影响
字段名数据库中的真实列名SQL 最终使用的字段。
字段别名字段的业务叫法帮助系统把用户自然语言映射到字段。
字段类型字段的语义类型影响字段适合做维度、度量、时间还是其他用途。
字段描述字段的业务解释帮助系统理解字段含义和使用边界。
索引管理控制字段是否建立索引或参与检索影响字段值检索、枚举匹配和问答效率。
隐藏控制字段是否对问答可见隐藏无关或敏感字段，减少误用。
字段用途指定字段适合做维度、过滤或度量影响答案构建器和问答中的字段选择。
表关系配置字段与其他表字段的关联影响多表问答时 JOIN 是否正确。
更新时间字段配置更新时间用于判断配置是否已更新。
操作编辑、查看或配置字段管理字段语义。

字段别名

字段别名用于连接数据库字段名和业务用户的自然语言表达。

建议为重要字段配置一个或多个常见业务叫法：

字段名建议别名
plan
plan
套餐、计划、版本、Plan
source
source
来源、渠道、获客来源
country
country
国家、地区
seats
seats
席位数、座席数
active_subscription
active_subscription
活跃订阅、是否活跃、有效订阅
created_at
created_at
创建时间、注册时间、开户时间

别名应使用业务用户真实会说的话，而不是复制字段名。

不建议：

  • 所有字段都只填英文列名。
  • 给多个不同字段配置相同别名。
  • 使用过于宽泛的别名，例如多个字段都叫“状态”。

字段描述

字段描述用于解释字段的业务含义、取值规则和注意事项。它比别名更详细，是减少误用字段的重要配置。

示例：

字段不推荐描述推荐描述
active_subscription
active_subscription
是否活跃标识账户当前是否有活跃订阅，TRUE 表示当前订阅有效，可用于统计活跃账户数。
seats
seats
席位当前账户购买或配置的席位数量，可用于计算总席位、活跃席位等指标。
canceled_at
canceled_at
取消时间账户取消订阅的时间。为空表示未取消，不应直接等同于活跃账户。
trial_converted
trial_converted
是否转化标识试用账户是否完成付费转化。

描述应回答三个问题：

  • 这个字段代表什么？
  • 什么时候可以使用它？
  • 它和相似字段有什么区别？

字段类型

实际操作中，字段类型可选项包括：

字段类型适用字段说明
CATEGORICAL
CATEGORICAL
plan
plan
、
source
source
、
country
country
、状态类字段		分类字段，适合分组、过滤和枚举值匹配。
CONTINUOUS
CONTINUOUS
seats
seats
、金额、数量、分数		连续数值字段，适合求和、平均、最大、最小等度量计算。
DATE_AND_TIME
DATE_AND_TIME
created_at
created_at
、
canceled_at
canceled_at
、时间戳字段		时间字段，适合时间过滤、趋势分析和时间分组。
PARTITION
PARTITION
分区字段分区过滤字段，常用于提升查询范围控制。
OTHER
OTHER
难以归类或暂不参与分析的字段不建议作为核心问答字段。

字段类型会影响系统判断字段适合做什么。例如，

seats
seats
更适合配置为连续数值，而不是分类维度；
plan
plan
更适合配置为分类字段。

字段用途

实际操作中，字段用途可选项包括：

字段用途含义典型字段
DIM
DIM
维度字段，适合分组展示
plan
plan
、
source
source
、
country
country
、日期字段
FILTER
FILTER
过滤字段，适合做筛选条件
plan
plan
、
source
source
、
active_subscription
active_subscription
、
created_at
created_at
MEASURE
MEASURE
度量字段，适合聚合计算
seats
seats
、金额、数量、时长

一个字段可能同时适合多个用途。例如 

plan
plan
既可以作为维度，也可以作为过滤条件；
created_at
created_at
既可以按时间过滤，也可以按时间分组。

配置建议：

字段类型推荐用途
分类字段
DIM
DIM
、
FILTER
FILTER
布尔字段
FILTER
FILTER
，必要时也可作为 
DIM
DIM
数值度量字段
MEASURE
MEASURE
，必要时可作为 
FILTER
FILTER
日期时间字段
FILTER
FILTER
、
DIM
DIM
ID、邮箱、姓名通常不建议作为默认 
DIM
DIM
，除非用于明细查询

隐藏字段

隐藏字段用于减少问答系统误用字段，也可以避免敏感或技术字段暴露给业务用户。在 Analytics Agent 的自然语言问答场景中，列隐藏也能起到类似列级权限的作用：被隐藏的字段不应作为模型优先理解、生成 SQL 或展示结果的字段。

需要注意，隐藏字段更偏向 Analytics Agent 问答层面的字段可见性控制；底层 Lakehouse 表权限仍应通过数据平台的权限体系管理。对于真正敏感的数据，应同时做好底层权限控制和字段隐藏配置。

建议隐藏：

  • 纯技术字段，如内部处理标识、同步批次号。
  • 用户不应直接查询的敏感字段。
  • 容易造成歧义但业务上不常用的字段。
  • 中间计算字段或临时字段。
  • 不希望在自然语言问答中暴露的列，例如手机号、邮箱、身份证号、内部成本字段等。

不建议隐藏：

  • 常用过滤字段。
  • 常用分组字段。
  • 指标计算依赖字段。
  • 答案构建器 SQL 中需要用到的字段。

隐藏字段前应确认是否有指标、答案构建器或常见问答依赖该字段。

可以把隐藏字段理解为分析域内的“语义可见性”配置：

使用目的示例
减少误用隐藏内部 ID、同步批次号，避免模型错误分组或过滤。
降低歧义多个相似状态字段中，只保留业务用户应使用的字段。
控制问答可见字段隐藏手机号、邮箱、身份证等不希望在问答中出现的字段。
简化用户体验让用户只看到和业务分析有关的字段。

索引配置

索引管理会影响字段值检索和枚举匹配。对自然语言问答来说，索引常用于帮助系统识别用户提到的具体取值。

适合关注索引的字段：

字段类型示例原因
枚举字段
plan
plan
、
source
source
、
country
country
用户经常按具体取值过滤，例如 “Basic Plan”“Google 来源”。
名称字段商品名、客户名、地区名用户可能直接说名称，需要匹配字段值。
分类层级字段一级类目、二级类目、行业分类用户常按类目筛选或分组。

不一定适合索引的字段：

  • 高基数且不常按值检索的 ID。
  • 连续数值字段。
  • 长文本备注字段。
  • 经常变化且问答不依赖枚举匹配的字段。

如果用户经常说某个字段值，但系统识别不稳定，应检查该字段是否已正确配置别名、描述和索引。

虚拟列

虚拟列用于在不修改底层表结构的情况下，为 Analytics Agent 增加一个更适合问答的派生字段。

实际操作中，可以创建类似下面的虚拟列：

concat(first_name, ' ', last_name)

用于把 

first_name
first_name
和 
last_name
last_name
拼接成完整姓名字段。

虚拟列适合以下场景：

场景示例
字段拼接拼接姓名、地区层级、编码和名称。
业务标签根据条件生成“活跃/非活跃”“高价值/普通”等标签。
格式标准化将大小写、空值、编码转换成更适合问答的格式。
简化常用表达将复杂表达式封装成一个语义字段。

创建虚拟列时应先运行验证，确认 SQL 表达式可执行，并查看样例结果是否符合预期。虚拟列创建后，也应补充别名、字段类型、字段用途和字段描述。

表关系字段

如果一个分析域包含多张表，字段关系会影响多表问答的 JOIN 是否正确。

实际操作中，单表时自动关联不可用；加入多张表后可以点击自动关联，系统会打开确认关联窗口，展示源表、源表列、目标表、目标列等信息。

表关系不仅出现在分析域的表列表中，也会体现在表详情的字段级配置里。实操中，

gaming_profiles_playstation
gaming_profiles_playstation
域的表列表显示：

  • history
    history
    关联到 
    players
    players
    ，关联字段为 
    playerid
    playerid
    。
  • purchased_games
    purchased_games
    关联到 
    players
    players
    ，关联字段为 
    playerid
    playerid
    。
  • purchased_games
    purchased_games
    通过游戏库字段关联到 
    games.gameid
    games.gameid
    。
  • achievements
    achievements
    关联到 
    games
    games
    ，关联字段为 
    gameid
    gameid
    。

进入表详情后，字段列表也能看到具体字段的表关联。例如 

purchased_games
purchased_games
表中的 
playerid
playerid
字段关联到玩家表，
library
library
字段关联到游戏表。字段级表关系会影响 Analytics Agent 在多表问题中如何选择 JOIN 路径。

一次实际多表问答中，用户询问“按游戏类型统计获得成就的玩家数和成就总数 Top 10”。系统生成 SQL 时使用了：

  • v_gpt_history.achievementid = v_gpt_achievements.achievementid
    v_gpt_history.achievementid = v_gpt_achievements.achievementid
  • v_gpt_achievements.gameid = v_gpt_games.gameid
    v_gpt_achievements.gameid = v_gpt_games.gameid

这说明表关系和字段语义能帮助系统从“玩家获得了什么成就”一路关联到“该成就属于哪款游戏、游戏类型是什么”。如果缺少这些关系，系统可能无法稳定找到中间表，或者需要依赖字段名猜测 JOIN。

需要注意：

  • 自动关联可能找不到关系，不能假设系统一定能自动识别。
  • 错误的关联会导致数据膨胀或结果错误。
  • 健康度扫描会把错误的 Join 关系视为严重影响问答正确性的异常。

建议：

  • 对事实表和维表的主外键关系进行人工确认。
  • 避免只凭字段名相同就确认关联。
  • 配置后用典型多表问题验证 SQL 中的 JOIN 是否符合预期。

数据预览和统计分析怎么用

字段语义配置前，建议先看数据预览和统计分析。

数据预览

数据预览用于确认字段真实取值。例如：

  • source
    source
    字段中真实值可能是 
    Google
    Google
    ，而不是用户说的 
    google
    google
    。
  • plan
    plan
    字段中可能有 
    Basic
    Basic
    、
    Business
    Business
    、
    Premium
    Premium
    。
  • 布尔字段可能使用 
    TRUE/FALSE
    TRUE/FALSE
    。

问答系统在实际执行时，可能会先查询字段真实取值，再使用正确大小写进行过滤。

统计分析

统计分析用于判断字段是否适合做维度、过滤或度量。

重点观察：

统计项用途
COUNT判断字段数据规模。
NULL VALUE判断字段是否大量为空。
DISTINCT判断字段基数，基数过高不适合作为默认维度。
MIN / MAX判断数值或时间范围。
AVERAGE / SUM判断数值字段是否适合作为度量。

例如，

id
id
的 DISTINCT 很高，通常不适合作为默认分组维度；
plan
plan
的 DISTINCT 较少，更适合做维度和过滤。

与指标和答案构建器的关系

字段语义配置会直接影响指标和答案构建器。

配置对指标的影响对答案构建器的影响
字段别名帮助用户用业务词命中指标帮助用户用自然语言指定过滤和维度
字段描述帮助系统理解指标口径帮助系统理解字段是否适合进入 SQL 模板参数
字段类型影响自动生成指标建议影响 
${filters}
${filters}
、
${dims}
${dims}
可选字段
字段用途影响聚合、过滤、分组判断决定字段更适合做 filter、dimension 还是 measure
隐藏字段避免指标误用字段避免构建器参数误选字段

实际验证中，答案构建器的 

${filters}
${filters}
字段范围通常比 
${dims}
${dims}
更宽；
${dims}
${dims}
更偏向分类、枚举、日期、布尔等适合分组的字段。

配置建议

优先配置核心字段

不要一开始试图把所有字段都配置得很完整。优先处理：

  • 用户最常问的业务字段。
  • 指标计算依赖字段。
  • 常用过滤字段。
  • 常用分组字段。
  • 多表关联字段。
  • 容易歧义的字段。

避免高基数字段默认作为维度

ID、邮箱、姓名、订单号这类字段虽然可以分组，但通常不适合作为业务分析维度。它们会导致结果过细，图表和表格难以解释。

除非用户明确要做明细查询，否则不建议把这类字段作为默认推荐维度。

时间字段要说明粒度

日期时间字段常用于趋势分析，但需要明确粒度：

  • 按天
  • 按周
  • 按月
  • 按季度
  • 按年

如果只配置“创建时间”，但不说明业务含义和常用粒度，系统可能生成过细或不符合业务习惯的时间分组。

布尔字段要写清 TRUE/FALSE 含义

布尔字段特别容易被误解。应在描述中写清：

  • TRUE 表示什么？
  • FALSE 表示什么？
  • 空值是否可能出现？
  • 是否可以直接用于业务口径？

例如：

配置后如何验证

字段语义配置完成后，不应只看页面是否保存成功，还应通过问答验证效果。

建议至少验证三类问题：

验证问题目的
“按 plan 展示账户数”验证字段能否作为维度。
“只看 Google 来源的活跃账户数”验证字段能否作为过滤条件，并能匹配真实取值。
“活跃账户数是多少”验证业务口径字段是否被正确理解。

验证时重点查看：

  • 最终答案是否正确。
  • SQL语句 是否使用了正确字段。
  • 记录 中是否命中了知识、指标或答案构建器。
  • 过滤条件是否使用了真实字段值和正确大小写。
  • 分组字段是否符合用户问题。

常见问题

问题可能原因处理建议
用户说“套餐”，系统没用 
plan
plan
未配置字段别名或描述给 
plan
plan
增加“套餐、计划、版本”等别名。
用户说“活跃账户”，系统不知道用哪个字段缺少业务口径描述或知识给 
active_subscription
active_subscription
补充描述，并配置知识说明活跃账户口径。
系统按 ID 分组，结果很碎高基数字段被当作维度调整字段用途，避免把 ID 作为默认维度。
过滤值大小写不对系统不知道字段真实枚举值查看数据预览，必要时配置索引或让系统先查询 DISTINCT。
答案构建器里看不到某个维度字段字段类型或用途不适合做维度检查字段类型、字段用途、隐藏状态。
健康度提示字段缺少描述字段语义未补全优先补充核心字段描述，再重新扫描健康度。
虚拟列能保存但问答不用缺少别名、描述或用途配置保存虚拟列后继续补充语义配置，并用问题验证。

上线前检查清单

  • 核心字段是否都有业务化别名。
  • 核心字段是否都有清晰描述。
  • 分类字段是否配置为适合维度或过滤。
  • 数值字段是否配置为适合度量。
  • 时间字段是否说明业务含义和常用粒度。
  • 布尔字段是否写清 TRUE/FALSE 含义。
  • 高基数字段是否避免作为默认维度。
  • 敏感或无关字段是否隐藏。
  • 常用枚举字段是否适合索引。
  • 虚拟列是否运行验证并补充语义配置。
  • 多表关联字段是否人工确认。
  • 是否用典型问题验证 SQL 和记录。

字段语义配置的目标不是把页面填满，而是让 Analytics Agent 能稳定理解业务问题，并生成符合业务口径的 SQL。

相关文档

配置分析域
配置虚拟列
Yunqi © 2024 Yunqi, Inc. All Rights Reserved.
联系我们
预约咨询
微信咨询
电话咨询
邮件咨询