Skip to content

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

fix: add json output alias on Retrieval node (#20394)

ciel9766c8c5483b
diff --git a/internal/agent/canvas/retrieval_json_output_test.go b/internal/agent/canvas/retrieval_json_output_test.go
new file mode 100644
index 0000000000..0a5d4c5ef4
--- /dev/null
+++ b/internal/agent/canvas/retrieval_json_output_test.go
@@ -0,0 +1,104 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+// retrieval_json_output_test.go — end-to-end regression for the Retrieval
+// node's `json` output on a zero-hit search.
+//
+// The tool envelope drops its chunk array when the search returns nothing, so
+// the node's `json` output used to be missing outright and a downstream
+// {{<id>@json}} template failed the run with "Can't find variable". This test
+// drives a full Begin → Retrieval → Message canvas so the component's output
+// contract and the template resolution are exercised together — the failure
+// the Agent chat surfaced.
+package canvas
+
+import (
+ "context"
+ "testing"
+
+ // Blank-import to trigger component init(), which installs the real
+ // component factory (same wiring as loop_semantics_test.go). Without it
+ // BuildWorkflow falls back to its placeholder echo body and the canvas
+ // never invokes the real Retrieval / Message components.
+ _ "ragflow/internal/agent/component"
+ "ragflow/internal/agent/runtime"
+
+ "gorm.io/gorm"
+)
+
+type zeroHitRetrievalService struct{}
+
+func (zeroHitRetrievalService) Search(context.Context, *gorm.DB, runtime.RetrievalRequest) ([]runtime.RetrievalChunk, error) {
+ return nil, nil
+}
+
+func TestRetrievalJSONOutputResolvesOnEmptySearch(t *testing.T) {
+ previous := runtime.GetRetrievalService()
+ runtime.SetRetrievalService(zeroHitRetrievalService{})
+ t.Cleanup(func() { runtime.SetRetrievalService(previous) })
+
+ dsl := &Canvas{
+ Components: map[string]CanvasComponent{
+ "begin": {
+ Obj: CanvasComponentObj{ComponentName: "Begin", Params: map[string]any{}},
+ Downstream: []string{"retrieval_0"},
+ },
+ "retrieval_0": {
+ Obj: CanvasComponentObj{ComponentName: "Retrieval", Params: map[string]any{
+ "retrieval_from": "dataset",
+ "kb_ids": []any{"kb-1"},
+ "query": "love",
+ }},
+ Upstream: []string{"begin"},
+ Downstream: []string{"message_0"},
+ },
+ "message_0": {
+ Obj: CanvasComponentObj{ComponentName: "Message", Params: map[string]any{
+ "text": "chunks: {retrieval_0@json}",
+ }},
+ Upstream: []string{"retrieval_0"},
+ Downstream: []string{},
+ },
+ },
+ Path: []string{"begin", "retrieval_0", "message_0"},
+ }
+
+ ctx := t.Context()
+ compiled, err := Compile(ctx, dsl)
+ if err != nil {
+ t.Fatalf("Compile: %v", err)
+ }
+ state := NewCanvasState("run-retrieval-json", "task-retrieval-json")
+ if _, runErr := compiled.Workflow.Invoke(withState(ctx, state), map[string]any{"query": "love"}); runErr != nil {
+ t.Fatalf("Invoke: %v", runErr)
+ }
+
+ chunks, err := state.GetVar("retrieval_0@json")
+ if err != nil {
+ t.Fatalf("GetVar(retrieval_0@json): %v", err)
+ }
+ values, ok := chunks.([]any)
+ if !ok || len(values) != 0 {
+ t.Fatalf("retrieval_0@json = %#v, want an empty array", chunks)
+ }
+ content, err := state.GetVar("message_0@content")
+ if err != nil {
+ t.Fatalf("GetVar(message_0@content): %v", err)
+ }
+ if content != "chunks: []" {
+ t.Fatalf("message_0@content = %#v, want %q", content, "chunks: []")
+ }
+}
diff --git a/internal/agent/component/retrieval_empty_response_test.go b/internal/agent/component/retrieval_empty_response_test.go
index d65686e3ee..b75c5c3b1f 100644
--- a/internal/agent/component/retrieval_empty_response_test.go
+++ b/internal/agent/component/retrieval_empty_response_test.go
@@ -18,6 +18,7 @@ package component
import (
"context"
+ "reflect"
"testing"
agenttool "ragflow/internal/agent/tool"
@@ -31,12 +32,59 @@ func (emptyRetrievalService) Search(context.Context, *gorm.DB, agenttool.Retriev
return []agenttool.RetrievalChunk{}, nil
}
-func TestRetrievalComponent_PreservesConfiguredEmptyResponse(t *testing.T) {
+// assertEmptyRetrievalOutputs pins the declared outputs of a Retrieval node
+// that produced no chunks: both names must resolve to an empty array so a
+// downstream {{<id>@json}} / {{<id>@chunks}} template does not fail with
+// "Can't find variable".
+func assertEmptyRetrievalOutputs(t *testing.T, output map[string]any) {
+ t.Helper()
+ for _, key := range []string{"json", "chunks"} {
+ value, ok := output[key].([]any)
+ if !ok {
+ t.Fatalf("%s = %#v, want an empty array", key, output[key])
+ }
+ if len(value) != 0 {
+ t.Fatalf("%s = %#v, want an empty array", key, value)
+ }
+ }
+}
+
+// TestRetrievalComponent_EmptyResultPreservesConfiguredEmptyResponse covers
+// the tool's early-return envelope (no retrieval_from configured): the
+// configured empty_response reaches formalized_content and the chunk outputs
+// stay resolvable.
+func TestRetrievalComponent_EmptyResultPreservesConfiguredEmptyResponse(t *testing.T) {
+ previous := agenttool.GetRetrievalService()
+ agenttool.SetRetrievalService(emptyRetrievalService{})
+ t.Cleanup(func() { agenttool.SetRetrievalService(previous) })
+
+ component, err := newRetrievalComponent(map[string]any{
+ "empty_response": "No relevant content.",
+ })
+ if err != nil {
+ t.Fatalf("newRetrievalComponent: %v", err)
+ }
+ output, err := component.Invoke(t.Context(), nil, map[string]any{"query": "love"})
+ if err != nil {
+ t.Fatalf("Invoke: %v", err)
+ }
+ if output["formalized_content"] != "No relevant content." {
+ t.Fatalf("formalized_content = %#v", output["formalized_content"])
+ }
+ assertEmptyRetrievalOutputs(t, output)
+}
+
+// TestRetrievalComponent_ZeroHitsExposeChunkOutputs covers the search path
+// that returns no hit: the tool envelope drops its `chunks` key (omitempty),
+// which previously left `json` unset and broke every downstream reference.
+func TestRetrievalComponent_ZeroHitsExposeChunkOutputs(t *testing.T) {
previous := agenttool.GetRetrievalService()
agenttool.SetRetrievalService(emptyRetrievalService{})
t.Cleanup(func() { agenttool.SetRetrievalService(previous) })
component, err := newRetrievalComponent(map[string]any{
+ "retrieval_from": "dataset",
+ "kb_ids": []any{"kb-1"},
"empty_response": "No relevant content.",
})
if err != nil {
@@ -49,4 +97,65 @@ func TestRetrievalComponent_PreservesConfiguredEmptyResponse(t *testing.T) {
if output["formalized_content"] != "No relevant content." {
t.Fatalf("formalized_content = %#v", output["formalized_content"])
}
+ assertEmptyRetrievalOutputs(t, output)
+}
+
+// TestRetrievalComponent_MissingDatasetExposeChunkOutputs covers the
+// no-dataset-selected early return: the node reports the configuration error
+// while still resolving every declared output.
+func TestRetrievalComponent_MissingDatasetExposeChunkOutputs(t *testing.T) {
+ component, err := newRetrievalComponent(map[string]any{
+ "retrieval_from": "dataset",
+ })
+ if err != nil {
+ t.Fatalf("newRetrievalComponent: %v", err)
+ }
+ output, err := component.Invoke(t.Context(), nil, map[string]any{"query": "love"})
+ if err != nil {
+ t.Fatalf("Invoke: %v", err)
+ }
+ if output["_ERROR"] != "No dataset is selected." {
+ t.Fatalf("_ERROR = %#v", output["_ERROR"])
+ }
+ if output["formalized_content"] != "" {
+ t.Fatalf("formalized_content = %#v, want empty string", output["formalized_content"])
+ }
+ assertEmptyRetrievalOutputs(t, output)
+}
+
+// TestRetrievalComponent_JSONOutputMirrorsChunks pins the alias itself: `json`
+// is the DSL-declared name for the same chunk array the tool reports as
+// `chunks`, so downstream templates see identical data under either name.
+func TestRetrievalComponent_JSONOutputMirrorsChunks(t *testing.T) {
+ previous := agenttool.GetRetrievalService()
+ agenttool.SetSimpleRetrievalService()
+ t.Cleanup(func() { agenttool.SetRetrievalService(previous) })
+
+ component, err := newRetrievalComponent(map[string]any{
+ "retrieval_from": "dataset",
+ "kb_ids": []any{"kb-1"},
+ "top_n": 1,
+ })
+ if err != nil {
+ t.Fatalf("newRetrievalComponent: %v", err)
+ }
+ output, err := component.Invoke(t.Context(), nil, map[string]any{"query": "ragflow"})
+ if err != nil {
+ t.Fatalf("Invoke: %v", err)
+ }
+ chunks, ok := output["chunks"].([]any)
+ if !ok || len(chunks) != 1 {
+ t.Fatalf("chunks = %#v, want one chunk", output["chunks"])
+ }
+ first, ok := chunks[0].(map[string]any)
+ if !ok || first["id"] != "simple-0" || first["content"] == "" {
+ t.Fatalf("chunk payload = %#v", chunks[0])
+ }
+ jsonOutput, ok := output["json"].([]any)
+ if !ok {
+ t.Fatalf("json = %#v, want an array", output["json"])
+ }
+ if !reflect.DeepEqual(jsonOutput, chunks) {
+ t.Fatalf("json = %#v, want the chunks array %#v", jsonOutput, chunks)
+ }
}
diff --git a/internal/agent/component/universe_a_wrappers.go b/internal/agent/component/universe_a_wrappers.go
index 2deb391735..2aec9db2b6 100644
--- a/internal/agent/component/universe_a_wrappers.go
+++ b/internal/agent/component/universe_a_wrappers.go
@@ -195,6 +195,7 @@ func (c *retrievalComponent) GetInputForm() map[string]any {
func (c *retrievalComponent) Outputs() map[string]string {
return map[string]string{
"formalized_content": "Rendered chunks for downstream LLM prompts.",
+ "json": "Chunk payloads under the DSL-declared output name (Array<Object>).",
"chunks": "Raw chunk payloads (id, document_id, content, score).",
}
}
@@ -218,7 +219,10 @@ func (c *retrievalComponent) Invoke(ctx context.Context, db *gorm.DB, inputs map
emptySelection = len(ids) == 0
}
if emptySelection {
- return map[string]any{"_ERROR": "No dataset is selected."}, nil
+ return normalizeRetrievalOutputs(map[string]any{
+ "_ERROR": "No dataset is selected.",
+ "formalized_content": "",
+ }), nil
}
}
common.Debug("agent retrieval component: invoke",
@@ -233,13 +237,9 @@ func (c *retrievalComponent) Invoke(ctx context.Context, db *gorm.DB, inputs map
common.Debug("agent retrieval component: output",
zap.String("tool_output", out),
)
- decoded := parseToolEnvelope(out)
- if chunks, ok := decoded["chunks"]; ok {
- if _, has := decoded["json"]; !has {
- decoded["json"] = chunks
- }
- }
- return decoded, nil
+
+ return normalizeRetrievalOutputs(parseToolEnvelope(out)), nil
+
}
func (c *retrievalComponent) Stream(_ context.Context, _ *gorm.DB, _ map[string]any) (<-chan map[string]any, error) {
@@ -254,6 +254,33 @@ func (c *retrievalComponent) Stream(_ context.Context, _ *gorm.DB, _ map[string]
return nil, nil
}
+// normalizeRetrievalOutputs pins the Retrieval node's chunk array under both
+// output names the canvas resolves: `json` (the DSL-declared output, typed
+// Array<Object> by the frontend) and `chunks` (the tool envelope's name).
+//
+// The tool marshals its envelope with `chunks` tagged omitempty, so a
+// zero-hit search drops the key outright, as does every early-return
+// envelope (empty query, search error, GraphRAG opt-in) and
+// parseToolEnvelope's `_raw` fallback. Without this, a downstream
+// {{<id>@json}} reference dies in ResolveTemplate with "Can't find variable"
+// instead of seeing the empty result set. Emptying the array — rather than
+// leaving the key absent or nil — is what every other tool-backed search
+// component emits unconditionally, and it is the shape callers iterate over.
+func normalizeRetrievalOutputs(decoded map[string]any) map[string]any {
+ if decoded == nil {
+ decoded = make(map[string]any, 3)
+ }
+ chunks, ok := decoded["chunks"]
+ if !ok || chunks == nil {
+ chunks = []any{}
+ }
+ decoded["chunks"] = chunks
+ if existing, has := decoded["json"]; !has || existing == nil {
+ decoded["json"] = chunks
+ }
+ return decoded
+}
+
// applyDefaults folds the node-level params into the per-call
// input map. Per-call values always win; node-level values fill
// the gaps. This mirrors Python's RetrievalParam semantics where