作者：路遙

點擊此處，查看視頻演示！

背景

在可觀測性系統中，UModel 定義了統一的數據模型（Schema），UModel 查詢專注於探索知識圖譜元數據，而 Entity 查詢則用於查詢和檢索具體的實體實例數據。Entity 查詢基於 USearch 引擎，提供了強大的全文檢索、精確查找、條件過濾等能力，支持跨域、跨實體類型的聯合查詢。

與 UModel 查詢關注 Schema 定義不同，Entity 查詢專注於運行時實體數據，幫助用户快速定位、檢索和分析具體的實體實例，如服務實例、Pod 實例、主機實例等。

1.1 Entity 查詢解決的問題

在實際的可觀測性場景中，我們經常需要：

1. 快速定位實體： 根據關鍵詞、屬性值快速找到相關實體
2. 跨域檢索： 在多個域（APM、K8s、雲資源等）中聯合搜索
3. 精確查詢： 根據已知的實體 ID 批量查詢詳細信息
4. 條件過濾： 基於實體屬性進行復雜的條件篩選
5. 統計分析： 對實體數據進行聚合分析和計算

Entity 查詢通過 USearch 引擎的統一接口，解決了傳統多系統查詢的痛點，提供了高效、靈活的實體檢索能力。

1.2 三種查詢類型的區別

在 EntityStore 中，存在三種不同類型的查詢：

EntityStore 是 UModel 系統中的統一存儲引擎，負責存儲和管理可觀測性領域的核心 Metadata 數據，包括 UModel 元數據、實體數據和實體關係數據。它為可觀測性分析提供高性能的數據存儲和查詢能力。

Entity 查詢專注於實體實例數據，是日常運維和問題排查中最常用的查詢方式。

Entity 查詢介紹

2.1 數據模型

三層存儲結構

USearch 採用分層存儲結構，確保數據的邏輯隔離和高效查詢：

1. Workspace 層： 最頂層隔離單位，不同 workspace 之間完全隔離
2. Domain 層： 域級別的分類，用於業務邏輯分組（如 apm、k8s、acs 等）
3. EntityType 層： 具體的實體類型，包含實際的實體數據（如 apm.service、k8s.pod 等）

Workspace: my-observability
├── Domain: apm
│   ├── EntityType: apm.service
│   ├── EntityType: apm.host  
│   └── EntityType: apm.instance
├── Domain: k8s
│   ├── EntityType: k8s.pod
│   ├── EntityType: k8s.node
│   └── EntityType: k8s.service
└── Domain: acs
    ├── EntityType: acs.ecs.instance
    └── EntityType: acs.rds.instance

數據存儲特點

• 唯一性保證： 在同一 EntityType 下，__entity_id__ 保證唯一性
• 列式存儲： 支持多行多列的表結構數據，支持 SPL 進行統計分析
• 索引優化： 針對檢索場景進行全文索引優化，支持多關鍵詞檢索和 Ranking 打分
• 時序支持： 支持基於時間範圍的數據查詢和過濾，支持回溯任意時刻的實體和關係狀態

2.2 USearch 核心功能

檢索能力

USearch 提供強大的全文檢索能力，支持：

• 多類型聯合檢索： 跨多個 domain 和 entity_type 進行聯合查詢，統一打分排序
• 多關鍵詞檢索打分： 基於詞權重、字段權重等信息計算相關性分數
• 智能分詞： 自動分詞和相關性打分，提高檢索準確性

-- 檢索所有domain中包含"cart"的實體
.entity with(domain='*', name='*', query='cart') 

掃描能力

除了檢索模式，USearch 還支持掃描模式，讀取原始數據後通過 SPL 進行更多的過濾和計算，適用於需要複雜數據處理的場景。

-- 掃描apm域中香港區域的應用數量
.entity with(domain='apm', name='apm.service') 
| where region_id = 'cn-hongkong'
| stats count = count() 

2.3 查詢語法

基礎語法結構

.entity with(
    domain='domain_pattern',     -- 域過濾模式
    name='type_pattern',         -- 類型過濾模式  
    query='search_query',        -- 查詢條件
    topk=10,                     -- 返回條數
    ids=['id1','id2','id3']      -- 精確ID查詢
)

參數詳解

fnmatch 語法説明： 支持通配符匹配，如 * 匹配任意字符，? 匹配單個字符。參考 fnmatch 文檔：https://docs.python.org/3/library/fnmatch.html。

域和類型過濾模式

-- 匹配模式示例
.entity with(domain='ac*')           -- ac開頭的domain
.entity with(domain='a*c')           -- a開頭、c結尾的domain  
.entity with(name='*instance')       -- 以instance結尾的類型
.entity with(name='k8s.*')           -- k8s域下的所有類型
.entity with(domain='*', name='*')   -- 所有domain和類型

查詢模式詳解

3.1 精確 ID 查詢

當知道具體的實體 ID 時，使用 ids 參數進行精確查詢：

-- 查詢特定ID的實體
.entity with(
    domain='apm', 
    name='apm.service', 
    ids=['4567bd905a719d197df','973ad511dad2a3f70a']
)

適用場景：

• 根據告警中的實體 ID 查詢詳細信息
• 驗證特定實體的存在性和狀態
• 批量查詢已知 ID 的實體信息

3.2 全文檢索模式

基礎全文搜索

-- 簡單關鍵詞搜索
.entity with(query='web application')
-- 多詞OR關係（默認行為）
.entity with(query='kubernetes docker container')

搜索特性：

• 多個詞之間是 OR 關係，出現任意一個詞即滿足條件
• 搜索所有字段，包括系統字段和自定義字段
• 自動分詞和相關性打分

短語搜索

對於通過符號連接（-）的詞，必須在同一字段下完整匹配：

-- 完整短語匹配
.entity with(query='opentelemetry.io/name-fraud-detection')
-- 普通搜索（命中任意一個詞）
.entity with(query='opentelemetry.io/name cart')

字段限定搜索

指定在特定字段中搜索：

-- 在描述字段中搜索
.entity with(query='description:"error handling service"')
-- 在自定義屬性中搜索
.entity with(query='cluster_name:production')
-- 在標籤中搜索
.entity with(query='labels.team:backend')

邏輯條件組合

支持 and、or、not 邏輯運算符：

-- AND條件：同時滿足兩個條件
.entity with(query='service_name:web AND status:running')
-- OR條件：滿足任一條件
.entity with(query='environment:prod OR environment:staging')
-- NOT條件：滿足左側、不滿足右側
.entity with(query='type:service NOT status:stopped')
-- 複雜組合
.entity with(query='(cluster:prod OR cluster:staging) AND NOT status:maintenance')

特殊字符處理：

• 包含特殊字符（如 |、:）的查詢必須用雙引號包含
• 示例：query='description:"ratio is 1:2"'

3.3 多類型聯合檢索

支持跨多個 domain 和 entity_type 進行聯合查詢，統一打分排序：

-- 檢索所有domain中包含"cart"的實體
.entity with(domain='*', name='*', query='cart') 
-- 檢索所有domain中包含"service"的實體類型，屬性中存在"production"的實體
.entity with(domain='*', name='*service*', query='production')
-- 檢索特定domain下的多種實體類型，屬性中存在"error"或"rate"的實體
.entity with(domain='apm', name='apm.*', query='error rate')

3.4 結合 SPL 進行數據計算分析

無論檢索模式還是掃描模式，都可以結合 SPL 進行更深入的數據計算：

-- 檢索apm域中在香港區域的不同語言的應用數量，按照應用數量降序排列
.entity with(domain='apm', name='apm.service') 
| where region_id = 'cn-hongkong'
| stats count = count() by language 
| project language, count 
| sort count desc

打分和排序機制

4.1 相關性打分

USearch 使用多因素綜合打分算法：

1. 詞頻權重： 關鍵詞在文檔中出現的頻率
2. 字段權重： 不同字段的重要性權重（如名稱字段權重高於描述字段）
3. 文檔長度： 較短文檔中的匹配通常得分更高
4. 逆文檔頻率： 稀有詞彙獲得更高權重

4.2 排序規則

默認按相關性分數降序排列，分數相同時按時間戳排序：

-- 默認相關性排序
.entity with(query='web service error', topk=20)
-- 結合SPL自定義排序
.entity with(query='kubernetes pod')
| sort __last_observed_time__ desc
| limit 50
-- 多字段排序
.entity with(domain='apm', name='apm.service')
| sort cluster asc, service_name asc

Entity 查詢具體應用場景

5.1 場景一：快速定位和檢索實體

問題描述： 線上出現告警或需要查找特定實體時，需要快速定位相關實體實例。

解決方案： 根據場景選擇不同的查詢方式。

-- 方式1：根據告警中的實體ID精確查詢
.entity with(
    domain='apm', 
    name='apm.service', 
    ids=['4567bd905a719d197df','973ad511dad2a3f70a']
)
-- 方式2：根據關鍵詞全文檢索
.entity with(query='user-service error', topk=10)
-- 方式3：字段限定精確查詢
.entity with(query='service_name:user-service')
-- 方式4：通過標籤查找特定團隊的服務
.entity with(
    domain='apm', 
    name='apm.service', 
    query='labels.team:backend AND labels.language:java AND status:running'
)

效果： 快速獲取問題實體的完整信息，包括狀態、屬性、標籤等，支持多種查詢方式滿足不同場景需求。

5.2 場景二：跨域聯合檢索

問題描述： 需要在多個域（APM、K8s、雲資源等）中搜索包含特定關鍵詞的實體，避免在多系統間切換。

解決方案： 使用多類型聯合檢索。

-- 在所有域中搜索包含"error"的實體
.entity with(domain='*', name='*', query='error', topk=50)
-- 檢索特定前綴domain下的多種實體類型
.entity with(domain='apm*', name='*', query='error', topk=50)

效果： 統一接口檢索跨域實體，打破數據孤島，提高查詢效率。

5.3 場景三：條件過濾和數據分析

問題描述： 需要找出滿足特定條件的實體，並進行統計分析，識別問題模式或進行數據洞察。

解決方案： 結合 SPL 進行條件過濾和聚合分析。

-- 找出java語言的apm服務，按集羣統計
.entity with(domain='apm', name='apm.service') 
| where language='java'
| stats count=count() by cluster
-- 查詢生產環境或預發環境中運行的服務
.entity with(query='(environment:prod OR environment:staging) AND status:running')
| stats count=count() by environment, cluster
-- 檢索apm域中ARMS生產應用在不同區域的數量，按照應用數量降序排列
.entity with(domain='apm', query='environment:prod') 
| where telemetry_client='ARMS' 
| stats service_count = count() by service, region_id 
| project region_id, service, service_count 
| sort service_count desc

效果： 快速識別問題實體，進行數據聚合分析，發現數據模式。

性能優化建議

6.1 使用精確匹配

字段限定查詢比全文搜索更高效：

-- ❌ 全文搜索（較慢）
.entity with(query='production')
-- ✅ 字段限定（更快）
.entity with(query='environment:production')

6.2 避免前綴通配符

後綴通配符比前綴通配符性能更好：

-- ❌ 前綴通配符（較慢）
.entity with(name='*service')
-- ✅ 後綴通配符（更快）
.entity with(name='service*')

6.3 合理使用邏輯運算符

簡單的 AND 條件比複雜的 OR 條件更高效：

-- ✅ 簡單AND條件
.entity with(query='status:running AND cluster:prod')
-- ⚠️ 複雜OR條件（性能較差）
.entity with(query='name:a OR name:b OR name:c OR name:d')

6.4 合理設置 topk

根據實際需求設置 topk 值，避免返回過多不必要的數據：

-- 只需要前10條結果
.entity with(query='error', topk=10)
-- 需要更多結果時再增加
.entity with(query='error', topk=100)

總結

Entity 查詢作為 EntityStore 中用於查詢實體實例的核心接口，為可觀測性場景提供了強大的檢索和分析能力。通過 Entity 查詢，用户可以：

1. 快速定位： 通過關鍵詞、ID、條件快速找到目標實體
2. 跨域檢索： 統一接口查詢多個域的實體數據
3. 精確查詢： 支持字段限定、邏輯組合等精確查詢方式
4. 數據分析： 結合 SPL 進行復雜的數據過濾和統計分析

這些能力使得 Entity 查詢成為日常運維、問題排查、數據分析等場景中不可或缺的工具，為可觀測性數據的有效利用提供了堅實的基礎。

點擊此處查看視頻演示。