Auto Ontology搜索API:跨语义层全文检索的正确姿势
Auto Ontology搜索API:跨语义层全文检索的正确姿势
Auto Ontology 是一个开源的 Python 框架,用于在数据之上构建语义化、基于图的推理层。它的全局搜索 API(/api/search/global-search)能让你用一行关键词,横跨数据库、表、列、术语(Term)、SQL 属性等 10 类对象做全文检索。本文面向新手,讲清楚这个 Auto Ontology 搜索 API 到底能搜什么、怎么匹配、过滤器怎么写,帮你避开最常见的三个坑。
搜索范围:一句话能覆盖 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 模块注释里:
- 词法分词 + 全词 AND:查询会先拆成 token,比如
created-at→created和at,命中要求每个 token 都出现。所以多词查询是"收窄"而不是"扩散"。 - 按字段分开匹配:名字命中要求所有 token 都在名字里;描述命中要求都在描述里。绝不会出现"一半 token 命中名字、一半命中描述"的怪异组合——否则会搜出一堆莫名其妙的列。
- 同义词走整词匹配:输入
unit能命中别名为Business Unit的 Term,但uni不行。避免子串匹配别名带来的"看不懂的噪声"。
此外还有两条实用边界:
- 最少 2 个字符:单字符查询直接返回空,因为
%a%会命中大半个目录,MIN_SEARCH_LENGTH 在进数据库之前就把请求挡掉了; - 最多返回 200 条:列表接口有
LIST_LIMIT = 200的硬上限,排序规则是——名字包含全部 token 的排最前,其次是靠别名命中的 Term,最后按名字长度升序(见 rank_key)。
💡 性能细节:子串匹配靠的是 Postgres 的
pg_trgmGIN 索引而非传统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)"。
三个容易翻车的点,一次说清
- count 和 list 条数可能不一致。列表有 200 上限,计数没有;而且即使列表已装满 200 条名字/描述命中,服务层还会给"仅靠别名命中的 Term"保留一小撮"救援名额"(synonym rescue,上限为页面大小的 10%),避免角标说有、列表里找不到。
- 查询词太短或被特殊字符吃掉会静默返回空。token 化后为空(比如只输标点)等于"什么都不匹配",而不是"匹配所有"。
- 同样的匹配逻辑被规则引擎复用。Auto Ontology 的"规则"就是一条保存下来的全局搜索请求(
search_term+text_match_option+filters),入库时重放同一套 match_selects 路径来给命中的对象自动打标签——也就是说,你在搜索框里看到的任何筛选组合,都可以原样固化成一条持续生效的规则。
小结
记住这张"速查卡"就能用好 Auto Ontology 搜索 API:
- 🎯 端点:
global-search取列表(≤200),global-search/count取分类计数; - 🔍 匹配:
contains子串、token 全 AND、同义词整词; - ⚙️ 放宽用
description/synonyms,收窄用objects/tags/data; - 📄 请求/响应契约以 auto_ontology/server/search/router.py 与 docs/openapi/auto-ontology-api.json 为准。
掌握这些,你在数据目录里的每一次搜索都会又快又可解释——这正是一个语义层该有的样子。

