搜尋結果

說明 KuraDB 如何分組 keyword 與 semantic 命中結果、哪些 field 保持私有，以及每筆結果的一致性保證。

分組

兩個 flat result set 都依首次出現的 source 分組，group 內維持排名順序。External representation 為：

[
  {
    "source": "/path/to/document.md",
    "matches": [
      {"chunk": 1, "content": "..."},
      {"chunk": 2, "content": "..."}
    ]
  }
]

REST 中已選 branch 無結果時表示為 []；MCP 的 search_rag 輸出則省略空 branch。

內部 field 在 serialization 前即被捨棄；對外的 Group 與 Match 型別只帶四個契約 field：

內部 field	保持私有的原因
Row ID	Storage implementation detail
Semantic score	Threshold 與 ranking 可能調整
Keyword hit count	內部 ranking signal
Chunk total	不屬於 consumer contract
Overall total	API 不提供 pagination metadata

Consumer 應只依賴 source、matches、chunk 與 content。