P2 Foundry

语义检索与对象查询：用业务语言查数

查数有三种姿势：语义检索"找口径"、对象查询"拉明细"、指标查询"算汇总"。本主题 4 个故事覆盖：用自然语言命中对象 / 属性 / 指标、用同义词提升命中率、用链接 traverse 跨对象过滤，以及在查不到时用指标目录补救。

业务分析师数据工程师语义检索对象查询指标 traverse 共 4 个故事

能 / 不能速览

✅ 这个主题能做

语义检索：输入业务语言（"华东客户的销售额"），返回匹配的对象 / 属性 / 指标及加权打分
对象查询：选对象、字段多选、过滤算子 eq / gte / lte / contains / in 等，外加布尔组合 and / or / not（≤3 层嵌套）
链接 traverse：用 customer_to_order.name 这类语法跨对象取字段并过滤
指标查询：total_gmv / aov 聚合取数，口径统一在指标语义层
同义词提升命中率；指标目录集中查看口径（formula）

⛔ 这个主题做不了

语义检索向量增强默认关闭，纯文本加权匹配，极端口语化可能命中不了
对象查询是 OOL 轻量版：单对象、最多 3 层深、禁止 "a.b.c" 三层点号引用（顶层一层 linkName.propName 兼容），复杂 join 要拆开分步查
order_to_product 是占位链接（join 表 order_items 不存在），查不到"某订单买了什么商品"
指标分组维度受限：total_gmv 只允许 created_at，按区域分组需要先在指标层加维度

适用角色

本主题面向两个角色：

业务分析师：不写 SQL，用语义检索找口径、对象查询拉明细、指标查询算汇总——是主要消费者。
数据工程师：维护属性同义词、指标口径（entity / measure / metric），让检索更准。

管理员负责对象级可见性与 RLS；业务决策者通过指标结论消费，不直接操作。

能力速览（能做什么）

语义检索

输入业务语言，返回匹配的 metric / object / property 三类结果，带命中字段与打分（name 1.0 > display_name 0.9 > synonyms 0.7 > description 0.3）。

对象查询

选对象、字段多选、过滤算子 eq / ne / gt / gte / lt / lte / like / contains / in / is_null + 布尔组合 and / or / not，参数白名单防注入；可用 api_name 定位（GET /ontology/query/:name）。

链接 traverse

用 "linkName.propName" 语法跨对象取字段（如 customer_to_order.name），自动 LEFT JOIN，最多 3 层深。

指标查询

total_gmv（SUM(amount)）、aov（SUM(amount)/COUNT(*)）聚合取数，支持时间范围过滤与允许维度分组。

指标目录

GET /metrics/catalog 集中查看每个指标的 entity / measure / formula / dimensions / owner / status。

调整指南（怎么调整）

想提命中率：给属性加同义词（region → 区域,大区），给指标配 synonyms（total_gmv → 销售额,GMV）。
想查跨对象：对象查询里用链接语法 customer_to_order.region 做 traverse；单对象内用 eq / gte / contains 精确过滤，复杂条件用 and / or / not 布尔组合（如"已发货且金额≥1000"）。
想限定范围：语义检索用 scopes 只搜 metric / object / property；filters 按 data_source 过滤；对象查询路径参数用 api_name 或内部 id 均可。
想算汇总：去指标查询选 total_gmv / aov，时间范围走 created_at 维度；分组维度受指标允许维度限制。
想对口径：指标目录看 formula（SUM(amount)/COUNT(*) 等），口径统一以指标层为准。

做得好的场景

用业务语言查数，让分析师不再等排期，特别适合以下场景：

业务自助取数：分析师不写 SQL，语义检索 + 对象查询秒级出数，替代以前写工单等 1~2 天。
口径统一：指标语义层集中管理 total_gmv / aov，不再靠人对公式。
跨对象分析：链接 traverse 免写 JOIN，从订单一路查到客户字段。
团队黑话可用：同义词让"区域、大区、销售额、GMV"都能命中。

限制与不足

以下是明确的边界，使用前先知道：

语义检索无向量增强：默认纯文本加权匹配，口语化或新词可能命中不了，需要配同义词；对象级可见性已生效（object_level_visible=true 时越权对象不返回，admin 全可见）。
对象查询是 OOL 轻量版：单对象、最多 3 层深、禁点号引用，跨对象复杂 join 要拆开分步查。
占位链接：order_to_product 的 join 表 order_items 仅为占位，当前查不到"某订单买了哪些商品"。
指标维度受限：total_gmv / aov 只允许 created_at 分组；按区域等维度分组需先在指标层加维度并走审批。
demo 数据重启重建：源表数据每次启动还原，但平台元数据与指标定义保留。

场景故事

故事 1 王姐搜"华东客户的销售额"：命中对象、属性与指标

场景：找口径角色：业务分析师耗时：约 5 分钟

背景: 王姐是业务分析师，被问到"华东客户贡献了多少销售额？"她不会 SQL，但平台上已有 customer / order 对象和 sales 指标口径（total_gmv、aov）。她打开"语义检索"，输入"华东客户销售额"。

传统做法对比: 以前要写工单给数据团队，等 1~2 天拿一张临时报表；口径对不对还得反复核对。现在语义检索 10 秒给出推荐口径，5 分钟出数。

角色: 业务分析师（只读查询权限即可，无需建模权限）。

操作步骤

打开"语义检索"，输入"华东客户销售额"
查看返回的对象 / 属性 / 指标及打分
用推荐的指标 total_gmv 去指标查询取总量
再到对象查询按明细核对

系统响应: 返回命中项：metric total_gmv（display_name 总销售额命中、synonyms 销售额命中，score 0.9）、object customer（display_name 客户命中，score 0.9）等，payload 带 measure / entity / formula / dimensions。空 query 返回 SEMANTIC_SEARCH_INVALID_QUERY。

结果洞察: 语义检索把"销售额"映射到指标 total_gmv（口径 SUM(amount)）、把"客户"映射到对象 customer；分析师不需要知道表结构，分析生效时间从天级变分钟级。

调整建议: 搜不到就加同义词；限定 scope（scopes:["metric"]）只搜指标更聚焦；filters 按 data_source 过滤多数据源场景。

动手试一试: 页面路径：侧边栏"语义检索"。输入内容：输入"华东客户销售额"。预期结果：命中 metric total_gmv（总销售额）与 object customer（客户），并显示匹配字段与打分。

限制提示: 向量增强默认关闭，纯文本加权匹配；极端口语化（如"华东那边卖得咋样"）可能命中不了，换关键词或加同义词。

故事 2 给属性加同义词：命中率肉眼可见地涨

场景：检索调优角色：数据工程师 + 分析师耗时：约 3 分钟

背景: 张工发现"区域"这个词在语义检索里什么都搜不到——因为属性名是 region、显示名是"地区"。他把"区域、大区"写进 region 的同义词，命中率立刻上来了。

传统做法对比: 以前靠人背术语表、反复试词，不知道"该搜什么词"；现在同义词直接挂在属性上，团队黑话也能命中检索。

角色: 数据工程师（维护同义词）；业务分析师（消费，检索更准）。

操作步骤

打开 customer 对象 → 属性 region
在 synonyms 字段填"区域,大区"（逗号分隔）
保存
语义检索输入"区域"验证命中

系统响应: 语义检索返回 property region，matched_fields 含 property_synonyms，score=0.7（synonyms 权重）；payload 带 object:customer、data_type:text、mapped_column:region。

结果洞察: 命中不再依赖属性名本身；权重设计 name(1.0) > display_name(0.9) > synonyms(0.7) > description(0.3)，团队黑话与系统命名解耦。

调整建议: 同义词用逗号分隔、覆盖各团队业务叫法；指标 total_gmv 的 synonyms（销售额,GMV）同理维护；命名规范了连同义词都能少配。

动手试一试: 页面路径：本体工作台 → customer → 属性 region。输入内容：synonyms 填"区域,大区"后保存。预期结果：语义检索搜"区域"或"大区"命中属性 region，score 0.7。

限制提示: 匹配是子串匹配（中文直接包含、英文小写包含）；对象没有 synonyms 字段，靠 name / display_name / category / description 匹配。

故事 3 对象查询 traverse：从订单一路查到华东客户的单子

场景：跨对象查询角色：业务分析师耗时：约 3 分钟

背景: 王姐要把"华东客户的订单"拉成明细。order 对象本身没有 region 字段，region 在 customer 上——她通过 customer_to_order 链接 traverse 过去，不用写 JOIN。

传统做法对比: 以前要手写 SQL 把两张表 JOIN 起来，还要知道外键叫什么；现在查询页面上"订单对象 + customer_to_order.region=华东"即可，秒级出结果。

角色: 业务分析师（只读查询权限）。

操作步骤

打开"对象查询"，选中 order 对象
字段选 order_id、amount、status、customer_to_order.name、customer_to_order.region
添加过滤条件 customer_to_order.region = 华东
执行查询

系统响应: 返回订单行：order_id=1（张三，995 元，shipped）、order_id=3（张三，1990 元，shipped）——华东客户张三的两单。底层自动 LEFT JOIN customers 并注入 RLS / CLS；字段不在本体属性集合时报校验错误。

结果洞察: 跨对象取数不用写 join，语义层自动翻译并做字段白名单防注入；"customer_to_order.name"或"customer.name"两种写法都能引用到客户字段。

调整建议: 单对象内用 eq / gte / contains 精确过滤；想按客户维度汇总，再配合指标层；复杂多跳关系拆成多次查询分步做。

动手试一试: 页面路径：侧边栏"对象查询"。输入内容：对象 order，字段含 customer_to_order.name / customer_to_order.region，过滤 region = 华东。预期结果：返回 2 条订单（order_id=1、order_id=3）。

限制提示: 对象查询是 OOL 轻量版：单对象、最多 3 层深、禁点号引用，跨对象复杂 join 要拆开分步查；order_to_product 占位链接查不到商品明细。

故事 4 查不到就查指标目录：搞懂对象查询 / 语义检索 / 指标的分工

场景：口径补救角色：业务分析师 + 数据工程师耗时：约 5 分钟

背景: 王姐想按客户维度看 GMV，但对象查询只能一行行拉数据，指标查询的 total_gmv 又只允许 created_at 分组。她打开"指标管理"看指标目录，搞懂了三者的分工。

传统做法对比: 以前"明细怎么查、口径怎么定、汇总怎么算"三个问题散落在 SQL、Excel、企微里；现在平台里对象查询 / 语义检索 / 指标三个入口各司其职，口径以指标目录为准。

角色: 业务分析师（消费）；数据工程师（维护指标口径与允许维度）。

操作步骤

打开"指标管理"（对应 GET /metrics/catalog）
看 total_gmv：entity=sales、measure=gmv、formula=SUM(amount)、允许维度 created_at
看 aov：formula=SUM(amount)/COUNT(*)
决定取数方式：明细用对象查询、汇总口径用指标查询、找口径用语义检索

系统响应

指标目录返回：

{
  "metrics": [
    {"name": "total_gmv", "display_name": "总销售额", "entity": "sales",
     "measures": ["gmv"], "formula": "SUM(amount)",
     "dimensions": ["created_at"], "status": "active"},
    {"name": "aov", "display_name": "客单价", "entity": "sales",
     "formula": "SUM(amount) / COUNT(*)", "status": "active"}
  ]
}

结果洞察: 三条路分工明确：语义检索=找口径，对象查询=查明细，指标查询=算汇总；口径（formula）统一在指标层，杜绝各算各的。

调整建议: 需求"按区域汇总"时，先给 sales 实体加 region 维度并配置进指标允许维度，走版本评审；先语义检索定位指标、再指标查询取数是最稳的路径。

动手试一试: 页面路径：侧边栏"指标管理"。输入内容：查看 total_gmv / aov 的 formula 与允许维度。预期结果：total_gmv=SUM(amount)、aov=SUM(amount)/COUNT(*)，再用指标查询查一次 total_gmv 看聚合结果。

限制提示: 指标分组维度受 allowed dimensions 限制（total_gmv 仅 created_at）；新增维度要先改实体定义（source_property 必须是对象属性）再更新指标允许维度；指标 deprecated 后不可查询。

常见问题

对象查询和语义检索有什么区别？

对象查询是"精确过滤"：明确选对象、加条件，适合已有明确目标；语义检索是"找口径"：输入业务语言返回匹配的对象、属性与指标，适合不确定去哪查时先探路；指标查询则是"算汇总"。

为什么我搜不到？

语义检索向量增强默认关闭，靠元数据 / 同义词文本加权匹配。加同义词、换关键词、或用 scopes 限定检索范围通常能解决。

怎么跨对象查询？

用链接 traverse 语法，如 customer_to_order.region；最多 3 层深、禁点号引用。复杂跨源 join 不在当前能力范围内，要拆开分步查。

指标和对象有什么关系？

指标 entity 引用对象（sales → order），度量基于对象属性（gmv=SUM(amount)）；口径 formula 统一在指标目录，查询由语义层翻译为聚合 SQL。

订单里的商品为什么查不到？

order_to_product 是 N:N 占位链接，join 表 order_items 在 demo 数据源中不存在；需要真实 join 表并导入元数据后才能查明细。

主题小结

一句话：查数三板斧——语义检索找口径、对象查询拉明细、指标查询算汇总，同义词让团队黑话也能命中。记住三个边界：向量增强默认关、单对象最多 3 层深、口径以指标目录为准。