Auto Ontology搜索API:跨语义层全文检索的正确姿势

原创2026-11-08 10:05:10119 阅读
文章标签:AI 应用MCP 服务数据治理知识图谱数据目录数据建模后端前端大模型人工智能

Auto Ontology搜索API:跨语义层全文检索的正确姿势

Auto Ontology 是一个开源的 Python 框架,用于在数据之上构建语义化、基于图的推理层。它的全局搜索 API(/api/search/global-search)能让你用一行关键词,横跨数据库、表、列、术语(Term)、SQL 属性等 10 类对象做全文检索。本文面向新手,讲清楚这个 Auto Ontology 搜索 API 到底能搜什么、怎么匹配、过滤器怎么写,帮你避开最常见的三个坑。

Auto Ontology 架构图,展示搜索 API 所在 Backend 与 Postgres 数据目录的调用链路

Auto Ontology 本体图谱,展示 Term、Table、Column、SQL Attribute 等可被全文检索的语义对象

搜索范围:一句话能覆盖 10 种对象

全局搜索不是只在"表名"里找,而是一次查询同时命中 10 张底层表、11 类对象:

对象类型 说明
Database / Schema 数据库与模式
Table / View 物理表与视图(视图在响应里以 table_type 区分)
Column 数据列
Custom Analysis / PQL Analysis 自定义分析
Term 业务术语,含别名(同义词)匹配
Column Attribute / SQL Attribute 列语义属性与 SQL 属性
Tag 标签本身(按标签名命中)

这套对象类型定义在 SEARCH_OBJECT_TYPES,响应里的 type 字段直接取自它,前端也用它来分组展示。

匹配规则:三个决定,全部可预测

理解规则后你就不需要"碰运气"。Auto Ontology 的搜索是纯子串匹配(contains 是唯一可用的 text_match_option),背后原因写在 dal/search.py 模块注释里:

  1. 词法分词 + 全词 AND:查询会先拆成 token,比如 created-at → created 和 at,命中要求每个 token 都出现。所以多词查询是"收窄"而不是"扩散"。
  2. 按字段分开匹配:名字命中要求所有 token 都在名字里;描述命中要求都在描述里。绝不会出现"一半 token 命中名字、一半命中描述"的怪异组合——否则会搜出一堆莫名其妙的列。
  3. 同义词走整词匹配:输入 unit 能命中别名为 Business Unit 的 Term,但 uni 不行。避免子串匹配别名带来的"看不懂的噪声"。

此外还有两条实用边界:

  • 最少 2 个字符:单字符查询直接返回空,因为 %a% 会命中大半个目录,MIN_SEARCH_LENGTH 在进数据库之前就把请求挡掉了;
  • 最多返回 200 条:列表接口有 LIST_LIMIT = 200 的硬上限,排序规则是——名字包含全部 token 的排最前,其次是靠别名命中的 Term,最后按名字长度升序(见 rank_key)。

💡 性能细节:子串匹配靠的是 Postgres 的 pg_trgm GIN 索引而非传统 tsvector 全文索引——后者只能命中词首,会悄悄漏掉"嵌在单词中间"的词。迁移文件 47ffb7499dfa_trigram_index_on_tag_name_for_global_.py 就是为全局搜索建这个索引的。

两个端点:取结果 vs 取数量

API 由两个 POST 端点组成,请求体完全相同,完整契约见 OpenAPI 定义:

  • /api/search/global-search:返回 { data, count },最多 200 条;
  • /api/search/global-search/count:返回按类型分组的真实命中数,无上限——专为 UI 的 tab 角标设计。

一条最简请求长这样:

{
  "search_term": "order",
  "text_match_option": "contains"
}

每条结果(GlobalSearchItem)包含:id、name、type、table_type、description、certified(是否认证)、breadcrumbs(从库到列的面包屑路径,方便前端直接渲染层级)和 synonyms(本次查询命中的别名列表)。前端对这两个端点的封装在 searchApi,类型定义在 types/search.ts。

五个过滤器:新手最该会用的是这几个

filters 里的字段分两类——放宽(把匹配范围从名字扩大到更多字段)和收窄(限定命中对象):

字段 方向 默认 用法要点
description 放宽 false 开之后才会搜描述文本,默认关闭是故意的——匹配自由文本是更"意外"的行为,需要你主动打开
synonyms 放宽 true 关闭后不再走别名匹配,结果里的 synonyms 也会全部清空
objects 收窄 不限 只搜指定类型,如只搜 ["Table", "Column"];传了未知类型会返回 422
tags 收窄 不限 标签 id 列表,命中其一即可;可混入哨兵值 "(blanks)" 表示"无标签对象"
data 收窄 不限 数据库/模式 id 混合列表,命中限定在其下的 Table、View、Column,其余类型一律排除

注意两个容易踩的点:

  • description 和 synonyms 默认值不同,这是刻意设计而非疏漏(GlobalSearchFilters 注释讲得很清楚);前端调用时会显式把两者都设为 true,所以你在 UI 里看到的"描述也搜"行为,直接调 API 时并不会默认拥有。
  • tags 收窄会顺带排除不可打标签的类型(Database、Schema、两类 Analysis)——除非你同时传入 "(blanks)"。

三个容易翻车的点,一次说清

  1. count 和 list 条数可能不一致。列表有 200 上限,计数没有;而且即使列表已装满 200 条名字/描述命中,服务层还会给"仅靠别名命中的 Term"保留一小撮"救援名额"(synonym rescue,上限为页面大小的 10%),避免角标说有、列表里找不到。
  2. 查询词太短或被特殊字符吃掉会静默返回空。token 化后为空(比如只输标点)等于"什么都不匹配",而不是"匹配所有"。
  3. 同样的匹配逻辑被规则引擎复用。Auto Ontology 的"规则"就是一条保存下来的全局搜索请求(search_term + text_match_option + filters),入库时重放同一套 match_selects 路径来给命中的对象自动打标签——也就是说,你在搜索框里看到的任何筛选组合,都可以原样固化成一条持续生效的规则。

小结

记住这张"速查卡"就能用好 Auto Ontology 搜索 API:

掌握这些,你在数据目录里的每一次搜索都会又快又可解释——这正是一个语义层该有的样子。

登录后查看全文
auto-ontology