Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix: support keywords in navigation APIs (#19645)

buua4368c9a0f65a1ab
diff --git a/internal/agent/tool/dataset_navigation.go b/internal/agent/tool/dataset_navigation.go
index 6dd1c4d8fe..ff368e4cd5 100644
--- a/internal/agent/tool/dataset_navigation.go
+++ b/internal/agent/tool/dataset_navigation.go
@@ -267,12 +267,12 @@ func (d *DatasetNavigationByTree) InvokableRun(ctx context.Context, argumentsInJ
// still applies — collect() filters these leaves.
if len(docs) == 0 {
for _, datasetID := range datasetIDs {
- clusters, _, err := ns.ListClusters(ctx, tenantID, datasetID, 0, 100)
+ clusters, _, err := ns.ListClusters(ctx, tenantID, datasetID, "", 0, 100)
if err != nil {
continue
}
for _, c := range clusters {
- children, _, err := ns.ListChildren(ctx, tenantID, datasetID, c.Name, 0, 100)
+ children, _, err := ns.ListChildren(ctx, tenantID, datasetID, c.Name, "", 0, 100)
if err != nil {
continue
}
diff --git a/internal/agent/tool/dataset_navigation_test.go b/internal/agent/tool/dataset_navigation_test.go
index 929378ab98..57743911a3 100644
--- a/internal/agent/tool/dataset_navigation_test.go
+++ b/internal/agent/tool/dataset_navigation_test.go
@@ -33,10 +33,10 @@ func (f *navRoutingFake) Search(_ context.Context, _, _ string, query string, _
f.mu.Unlock()
return f.hits, nil
}
-func (f *navRoutingFake) ListClusters(context.Context, string, string, int, int) ([]nav.NavNode, int64, error) {
+func (f *navRoutingFake) ListClusters(context.Context, string, string, string, int, int) ([]nav.NavNode, int64, error) {
return f.clusters, int64(len(f.clusters)), nil
}
-func (f *navRoutingFake) ListChildren(_ context.Context, _, _, name string, _, _ int) ([]nav.NavNode, int64, error) {
+func (f *navRoutingFake) ListChildren(_ context.Context, _, _, name, _ string, _, _ int) ([]nav.NavNode, int64, error) {
return f.children[name], int64(len(f.children[name])), nil
}
func (f *navRoutingFake) SummariesByDocIDs(context.Context, string, string, []string) map[string]string {
diff --git a/internal/handler/dataset_artifact.go b/internal/handler/dataset_artifact.go
index 9afaf8ea8b..9e0d02bb96 100644
--- a/internal/handler/dataset_artifact.go
+++ b/internal/handler/dataset_artifact.go
@@ -321,13 +321,15 @@ func (h *DatasetArtifactHandler) AnySkill(c *gin.Context) {
}
}
-// ListNavigation handles GET /navigation — list navigation clusters.
+// ListNavigation handles GET /navigation — list navigation clusters. The
+// optional keywords query searches navigation rows across the dataset.
func (h *DatasetArtifactHandler) ListNavigation(c *gin.Context) {
_, tenantID, _ := h.datasetOwner(c, c.Param("dataset_id"))
if tenantID == "" {
return
}
- items, total, err := h.svc.ListNavClusters(c.Request.Context(), tenantID, c.Param("dataset_id"))
+ keywords := strings.TrimSpace(c.Query("keywords"))
+ items, total, err := h.svc.ListNavClusters(c.Request.Context(), tenantID, c.Param("dataset_id"), keywords)
if err != nil {
common.ErrorWithCode(c, common.CodeDataError, err.Error())
return
@@ -337,13 +339,15 @@ func (h *DatasetArtifactHandler) ListNavigation(c *gin.Context) {
common.SuccessWithData(c, gin.H{"total": total, "items": items}, "success")
}
-// ListNavigationChildren handles GET /navigation/<name>/children — list children of a navigation cluster.
+// ListNavigationChildren handles GET /navigation/<name>/children — list
+// children of a navigation cluster, optionally filtered by keywords.
func (h *DatasetArtifactHandler) ListNavigationChildren(c *gin.Context) {
_, tenantID, _ := h.datasetOwner(c, c.Param("dataset_id"))
if tenantID == "" {
return
}
- items, total, err := h.svc.ListNavChildren(c.Request.Context(), tenantID, c.Param("dataset_id"), c.Param("name"))
+ keywords := strings.TrimSpace(c.Query("keywords"))
+ items, total, err := h.svc.ListNavChildren(c.Request.Context(), tenantID, c.Param("dataset_id"), c.Param("name"), keywords)
if err != nil {
common.ErrorWithCode(c, common.CodeDataError, err.Error())
return
diff --git a/internal/service/dataset_artifact_service.go b/internal/service/dataset_artifact_service.go
index 0f8506a9f0..4afd1f9b18 100644
--- a/internal/service/dataset_artifact_service.go
+++ b/internal/service/dataset_artifact_service.go
@@ -866,17 +866,17 @@ func (s *DatasetArtifactService) DeleteDocumentGraph(ctx context.Context, tenant
return len(ids), nil
}
-// ListNavClusters returns the navigation clusters of a dataset. It delegates to
-// the ES-backed NavService and returns the frontend DatasetNavNode shape
-// (snake_case NavNode JSON), matching Python GET /navigation exactly. The old
-// NavigationItem{name,title,count} shape did not match the frontend interface
-// and has been removed.
-func (s *DatasetArtifactService) ListNavClusters(ctx context.Context, tenantID, datasetID string) ([]nav.NavNode, int64, error) {
+// ListNavClusters returns the navigation clusters of a dataset. A non-empty
+// keywords value searches the navigation rows instead of limiting the result
+// to root clusters. It delegates to the ES-backed NavService and returns the
+// frontend DatasetNavNode shape (snake_case NavNode JSON), matching Python GET
+// /navigation.
+func (s *DatasetArtifactService) ListNavClusters(ctx context.Context, tenantID, datasetID, keywords string) ([]nav.NavNode, int64, error) {
ns := nav.GetNavService()
if ns == nil {
return nil, 0, fmt.Errorf("datasetnav: NavService not initialized (SetNavService must be called at bootstrap)")
}
- nodes, total, err := ns.ListClusters(ctx, tenantID, datasetID, 0, 10000)
+ nodes, total, err := ns.ListClusters(ctx, tenantID, datasetID, keywords, 0, 10000)
if err != nil {
return nil, 0, err
}
@@ -884,13 +884,13 @@ func (s *DatasetArtifactService) ListNavClusters(ctx context.Context, tenantID,
}
// ListNavChildren returns the children of a navigation cluster in the frontend
-// DatasetNavNode shape.
-func (s *DatasetArtifactService) ListNavChildren(ctx context.Context, tenantID, datasetID, name string) ([]nav.NavNode, int64, error) {
+// DatasetNavNode shape, optionally filtered by keywords.
+func (s *DatasetArtifactService) ListNavChildren(ctx context.Context, tenantID, datasetID, name, keywords string) ([]nav.NavNode, int64, error) {
ns := nav.GetNavService()
if ns == nil {
return nil, 0, fmt.Errorf("datasetnav: NavService not initialized (SetNavService must be called at bootstrap)")
}
- nodes, total, err := ns.ListChildren(ctx, tenantID, datasetID, name, 0, 10000)
+ nodes, total, err := ns.ListChildren(ctx, tenantID, datasetID, name, keywords, 0, 10000)
if err != nil {
return nil, 0, err
}
diff --git a/internal/service/nav/nav.go b/internal/service/nav/nav.go
index f65b3ca81d..c24150624c 100644
--- a/internal/service/nav/nav.go
+++ b/internal/service/nav/nav.go
@@ -97,10 +97,12 @@ type NavService interface {
// returned coverage is trimmed to the scope so no out-of-scope document
// surfaces under a cluster that merely overlaps it.
Search(ctx context.Context, tenantID, kbID, query string, embd []float32, docScope []string, topK int) ([]NavHit, error)
- // ListClusters returns the depth-0 clusters (parent_kwd=root).
- ListClusters(ctx context.Context, tenantID, kbID string, page, pageSize int) ([]NavNode, int64, error)
- // ListChildren returns the direct children of a cluster (parent_kwd=name).
- ListChildren(ctx context.Context, tenantID, kbID, name string, page, pageSize int) ([]NavNode, int64, error)
+ // ListClusters returns the depth-0 clusters (parent_kwd=root). When
+ // keywords is non-empty, it returns matching navigation nodes instead.
+ ListClusters(ctx context.Context, tenantID, kbID, keywords string, page, pageSize int) ([]NavNode, int64, error)
+ // ListChildren returns the direct children of a cluster (parent_kwd=name),
+ // optionally filtered by keywords.
+ ListChildren(ctx context.Context, tenantID, kbID, name, keywords string, page, pageSize int) ([]NavNode, int64, error)
// SummariesByDocIDs returns the nav_doc summary (preferred readable name, else
// the payload description) keyed by doc_id for the given documents. It mirrors
// Python dataset_api_service._nav_doc_summaries and backs the chunk_agg
diff --git a/internal/service/nav/nav_service_router_test.go b/internal/service/nav/nav_service_router_test.go
index d0d9847f1e..6d98d404ad 100644
--- a/internal/service/nav/nav_service_router_test.go
+++ b/internal/service/nav/nav_service_router_test.go
@@ -37,10 +37,10 @@ func (f *scopeRecordingNav) Search(_ context.Context, _, _ string, _ string, _ [
f.scope = append([]string(nil), docScope...)
return f.hits, nil
}
-func (f *scopeRecordingNav) ListClusters(context.Context, string, string, int, int) ([]NavNode, int64, error) {
+func (f *scopeRecordingNav) ListClusters(context.Context, string, string, string, int, int) ([]NavNode, int64, error) {
return nil, 0, nil
}
-func (f *scopeRecordingNav) ListChildren(context.Context, string, string, string, int, int) ([]NavNode, int64, error) {
+func (f *scopeRecordingNav) ListChildren(context.Context, string, string, string, string, int, int) ([]NavNode, int64, error) {
return nil, 0, nil
}
func (f *scopeRecordingNav) SummariesByDocIDs(context.Context, string, string, []string) map[string]string {
diff --git a/internal/service/nlp/datasetnav.go b/internal/service/nlp/datasetnav.go
index 276d523ba9..20ed96b3ac 100644
--- a/internal/service/nlp/datasetnav.go
+++ b/internal/service/nlp/datasetnav.go
@@ -148,18 +148,24 @@ func (s *NavService) navSearch(ctx context.Context, tenantID, kbID string, filte
return res.Chunks, res.Total, nil
}
-// ListClusters returns the depth-0 clusters (parent_kwd=root).
-func (s *NavService) ListClusters(ctx context.Context, tenantID, kbID string, page, pageSize int) ([]nav.NavNode, int64, error) {
+// ListClusters returns the depth-0 clusters (parent_kwd=root). When keywords
+// is non-empty, it searches all navigation rows by their indexed summary and
+// returns matching nodes, mirroring the Python endpoint's search mode.
+func (s *NavService) ListClusters(ctx context.Context, tenantID, kbID, keywords string, page, pageSize int) ([]nav.NavNode, int64, error) {
if pageSize <= 0 {
pageSize = 100
}
offset := page * pageSize
- chunks, total, err := s.navSearch(ctx, tenantID, kbID,
- navFilter(map[string]interface{}{
- "type_kwd": []string{"nav_cluster"},
- "parent_kwd": []string{navRootParent},
- }),
- []string{"title_kwd", "content_with_weight", "doc_count_int", "type_kwd"}, offset, pageSize, nil)
+ filter := navFilter(map[string]interface{}{
+ "type_kwd": []string{"nav_cluster"},
+ "parent_kwd": []string{navRootParent},
+ })
+ if strings.TrimSpace(keywords) != "" {
+ filter = navFilter(nil)
+ }
+ matchExpressions := navKeywordExpressions(keywords)
+ chunks, total, err := s.navSearch(ctx, tenantID, kbID, filter,
+ []string{"title_kwd", "content_with_weight", "doc_count_int", "type_kwd", "doc_id"}, offset, pageSize, matchExpressions)
if err != nil {
return nil, 0, err
}
@@ -170,15 +176,17 @@ func (s *NavService) ListClusters(ctx context.Context, tenantID, kbID string, pa
return nodes, total, nil
}
-// ListChildren returns the direct children of a cluster (parent_kwd=name).
-func (s *NavService) ListChildren(ctx context.Context, tenantID, kbID, name string, page, pageSize int) ([]nav.NavNode, int64, error) {
+// ListChildren returns the direct children of a cluster (parent_kwd=name),
+// optionally filtered by keywords.
+func (s *NavService) ListChildren(ctx context.Context, tenantID, kbID, name, keywords string, page, pageSize int) ([]nav.NavNode, int64, error) {
if pageSize <= 0 {
pageSize = 100
}
offset := page * pageSize
chunks, total, err := s.navSearch(ctx, tenantID, kbID,
navFilter(map[string]interface{}{"parent_kwd": []string{name}}),
- []string{"title_kwd", "content_with_weight", "doc_count_int", "type_kwd", "doc_id"}, offset, pageSize, nil)
+ []string{"title_kwd", "content_with_weight", "doc_count_int", "type_kwd", "doc_id"}, offset, pageSize,
+ navKeywordExpressions(keywords))
if err != nil {
return nil, 0, err
}
@@ -194,6 +202,21 @@ func (s *NavService) ListChildren(ctx context.Context, tenantID, kbID, name stri
return nodes, total, nil
}
+// navKeywordExpressions builds the lexical search expression used by the REST
+// navigation endpoints. These are the same indexed summary fields used by the
+// Python navigation search, with a stronger weight on the main content field.
+func navKeywordExpressions(keywords string) []interface{} {
+ keywords = strings.TrimSpace(keywords)
+ if keywords == "" {
+ return nil
+ }
+ return []interface{}{&types.MatchTextExpr{
+ Fields: []string{"content_ltks^10", "content_sm_ltks"},
+ MatchingText: keywords,
+ TopN: 10000,
+ }}
+}
+
// nodeFromRow converts an engine row into a NavNode.
func (s *NavService) nodeFromRow(row map[string]interface{}, fallbackType string) nav.NavNode {
name := firstStringValue(row["title_kwd"])
diff --git a/internal/service/nlp/datasetnav_test.go b/internal/service/nlp/datasetnav_test.go
index 214e80832c..753aad9d64 100644
--- a/internal/service/nlp/datasetnav_test.go
+++ b/internal/service/nlp/datasetnav_test.go
@@ -326,7 +326,7 @@ func TestNavService_ListClusters_FiltersRoot(t *testing.T) {
if err := ns.UpsertDoc(t.Context(), navUpsertInput("t1", "kb1", "d1", "aaa")); err != nil {
t.Fatal(err)
}
- clusters, total, err := ns.ListClusters(t.Context(), "t1", "kb1", 0, 10)
+ clusters, total, err := ns.ListClusters(t.Context(), "t1", "kb1", "", 0, 10)
if err != nil {
t.Fatal(err)
}
@@ -652,7 +652,7 @@ func TestNavService_Acceptance4_ListChildren(t *testing.T) {
if err := ns.UpsertDoc(t.Context(), navUpsertInput("t1", "kb1", "d2", "aaa two")); err != nil {
t.Fatal(err)
}
- clusters, _, err := ns.ListClusters(t.Context(), "t1", "kb1", 0, 10)
+ clusters, _, err := ns.ListClusters(t.Context(), "t1", "kb1", "", 0, 10)
if err != nil {
t.Fatal(err)
}
@@ -663,7 +663,7 @@ func TestNavService_Acceptance4_ListChildren(t *testing.T) {
t.Fatalf("cluster doc_count = %d, want 2 (both docs merged into the cluster)", clusters[0].DocCount)
}
name := clusters[0].Name
- children, total, err := ns.ListChildren(t.Context(), "t1", "kb1", name, 0, 10)
+ children, total, err := ns.ListChildren(t.Context(), "t1", "kb1", name, "", 0, 10)
if err != nil {
t.Fatal(err)
}