Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(graph): preserve relationship direction and document provenance (#3950)

knqiufane29301115a27
diff --git a/internal/agent/tools/query_knowledge_graph.go b/internal/agent/tools/query_knowledge_graph.go
index 1a7e809a3..fa36e13a9 100644
--- a/internal/agent/tools/query_knowledge_graph.go
+++ b/internal/agent/tools/query_knowledge_graph.go
@@ -708,29 +708,33 @@ func searchTargetsCoverWholeKB(targets types.SearchTargets, kbID string) bool {
return false
}
-// relationsBackedBy keeps the graph's relations whose two entities were both
-// extracted from one of the evidence chunks. Entities whose chunks are not
-// among them cannot be shown to be in scope, so their relations are dropped.
+// relationsBackedBy checks the actual endpoint instances against scoped evidence.
+// A same-named entity in another document cannot establish a relation's scope.
func relationsBackedBy(graph *types.GraphData, evidence []*types.SearchResult) []*types.GraphRelation {
if graph == nil || len(evidence) == 0 {
return nil
}
allowedChunks := make(map[string]bool, len(evidence))
for _, r := range evidence {
- allowedChunks[r.ID] = true
+ if r != nil {
+ allowedChunks[r.ID] = true
+ }
}
allowedNodes := make(map[string]bool)
for _, node := range graph.Node {
+ if node == nil || node.ID == "" {
+ continue
+ }
for _, id := range node.Chunks {
if allowedChunks[id] {
- allowedNodes[node.Name] = true
+ allowedNodes[node.ID] = true
break
}
}
}
var relations []*types.GraphRelation
for _, rel := range graph.Relation {
- if allowedNodes[rel.Node1] && allowedNodes[rel.Node2] {
+ if rel != nil && allowedNodes[rel.SourceID] && allowedNodes[rel.TargetID] {
relations = append(relations, rel)
}
}
diff --git a/internal/agent/tools/query_knowledge_graph_graph_test.go b/internal/agent/tools/query_knowledge_graph_graph_test.go
index 747a7e954..ad5f1a50e 100644
--- a/internal/agent/tools/query_knowledge_graph_graph_test.go
+++ b/internal/agent/tools/query_knowledge_graph_graph_test.go
@@ -95,13 +95,13 @@ func TestQueryKnowledgeGraph_QueriesTheGraph(t *testing.T) {
func TestQueryKnowledgeGraph_ScopesRelationsToDocuments(t *testing.T) {
graphRepo := &stubGraphRepo{graph: &types.GraphData{
Node: []*types.GraphNode{
- {Name: "Docker", Chunks: []string{"c-a"}},
- {Name: "Kubernetes", Chunks: []string{"c-a"}},
- {Name: "Secret", Chunks: []string{"c-b"}},
+ {Name: "Docker", ID: "docker-a", Chunks: []string{"c-a"}},
+ {Name: "Kubernetes", ID: "k8s-a", Chunks: []string{"c-a"}},
+ {Name: "Secret", ID: "secret-b", Chunks: []string{"c-b"}},
},
Relation: []*types.GraphRelation{
- {Node1: "Kubernetes", Node2: "Docker", Type: "orchestrates"},
- {Node1: "Secret", Node2: "Docker", Type: "leaks"},
+ {Node1: "Kubernetes", Node2: "Docker", Type: "orchestrates", SourceID: "k8s-a", TargetID: "docker-a"},
+ {Node1: "Secret", Node2: "Docker", Type: "leaks", SourceID: "secret-b", TargetID: "docker-a"},
},
}}
chunkRepo := &stubGraphChunkRepo{chunks: map[string]*types.Chunk{
@@ -131,3 +131,115 @@ func TestQueryKnowledgeGraph_ScopesRelationsToDocuments(t *testing.T) {
require.Len(t, errs, 1, "the failed text search is reported beside the graph hits")
assert.Contains(t, errs[0], "text search failed")
}
+
+type graphScopeKnowledgeService struct {
+ scopeKnowledgeService
+}
+
+func (*graphScopeKnowledgeService) GetKnowledgeBatchWithSharedAccess(
+ _ context.Context, _ uint64, ids []string,
+) ([]*types.Knowledge, error) {
+ var documents []*types.Knowledge
+ for _, id := range ids {
+ documents = append(documents, &types.Knowledge{ID: id, Title: id, KnowledgeBaseID: "kb-1"})
+ }
+ return documents, nil
+}
+
+func TestQueryKnowledgeGraph_SameNamedDocumentInstances(t *testing.T) {
+ graph := &types.GraphData{
+ Node: []*types.GraphNode{
+ {Name: "Acme", ID: "acme-a", KnowledgeID: "doc-a", Chunks: []string{"c-a"}},
+ {Name: "Shanghai", ID: "city-a", KnowledgeID: "doc-a", Chunks: []string{"c-a"}},
+ {Name: "Acme", ID: "acme-b", KnowledgeID: "doc-b", Chunks: []string{"c-b"}},
+ {Name: "Shanghai", ID: "city-b", KnowledgeID: "doc-b", Chunks: []string{"c-b"}},
+ },
+ Relation: []*types.GraphRelation{
+ {Node1: "Acme", Node2: "Shanghai", Type: "HEADQUARTERED_IN", SourceID: "acme-a", TargetID: "city-a"},
+ {Node1: "Acme", Node2: "Shanghai", Type: "HAS_BRANCH_IN", SourceID: "acme-b", TargetID: "city-b"},
+ },
+ }
+ chunks := &stubGraphChunkRepo{chunks: map[string]*types.Chunk{
+ "c-a": {ID: "c-a", KnowledgeID: "doc-a", KnowledgeBaseID: "kb-1", Content: "doc a", IsEnabled: true},
+ "c-b": {ID: "c-b", KnowledgeID: "doc-b", KnowledgeBaseID: "kb-1", Content: "doc b", IsEnabled: true},
+ }}
+ service := &graphScopeKnowledgeService{scopeKnowledgeService: scopeKnowledgeService{
+ tags: map[string][]*types.KnowledgeTag{
+ "doc-a": {testKnowledgeTag("tag-a")},
+ "doc-b": {testKnowledgeTag("tag-b")},
+ },
+ }}
+ for _, tt := range []struct {
+ name string
+ target *types.SearchTarget
+ chunks []string
+ relations []string
+ }{
+ {
+ "whole KB", &types.SearchTarget{Type: types.SearchTargetTypeKnowledgeBase, KnowledgeBaseID: "kb-1"},
+ []string{"c-a", "c-b"},
+ []string{"HEADQUARTERED_IN", "HAS_BRANCH_IN"},
+ },
+ {"first document", &types.SearchTarget{
+ Type: types.SearchTargetTypeKnowledge, KnowledgeBaseID: "kb-1",
+ KnowledgeIDs: []string{"doc-a"},
+ }, []string{"c-a"}, []string{"HEADQUARTERED_IN"}},
+ {"second document", &types.SearchTarget{
+ Type: types.SearchTargetTypeKnowledge, KnowledgeBaseID: "kb-1",
+ KnowledgeIDs: []string{"doc-b"},
+ }, []string{"c-b"}, []string{"HAS_BRANCH_IN"}},
+ {"tag scope", &types.SearchTarget{
+ Type: types.SearchTargetTypeKnowledgeBase, KnowledgeBaseID: "kb-1",
+ TagIDs: []string{"tag-b"},
+ }, []string{"c-b"}, []string{"HAS_BRANCH_IN"}},
+ } {
+ t.Run(tt.name, func(t *testing.T) {
+ tool := NewQueryKnowledgeGraphTool(&stubKnowledgeBaseService{
+ kb: &types.KnowledgeBase{ID: "kb-1", ExtractConfig: &types.ExtractConfig{
+ Enabled: true, Nodes: []*types.GraphNode{{Name: "company"}},
+ }},
+ }, types.SearchTargets{tt.target}).WithGraph(&stubGraphRepo{graph: graph}, chunks).
+ WithKnowledgeScope(service)
+ args, err := json.Marshal(QueryKnowledgeGraphInput{KnowledgeBaseIDs: []string{"kb-1"}, Query: "Shanghai"})
+ require.NoError(t, err)
+ result, err := tool.Execute(context.Background(), args)
+ require.NoError(t, err)
+ require.True(t, result.Success)
+ rows := result.Data["results"].([]map[string]interface{})
+ var ids []string
+ for _, row := range rows {
+ ids = append(ids, row["chunk_id"].(string))
+ }
+ assert.ElementsMatch(t, tt.chunks, ids)
+ var relationTypes []string
+ for _, relation := range result.Data["relations"].([]map[string]interface{}) {
+ assert.Equal(t, "Acme", relation["source"])
+ assert.Equal(t, "Shanghai", relation["target"])
+ relationTypes = append(relationTypes, relation["type"].(string))
+ }
+ assert.ElementsMatch(t, tt.relations, relationTypes,
+ "each relation must be supported by its own endpoint instances")
+ })
+ }
+}
+
+func TestRelationsBackedByRejectsMissingOrForeignEndpointIdentities(t *testing.T) {
+ graph := &types.GraphData{
+ Node: []*types.GraphNode{
+ {Name: "Acme", ID: "acme-a", Chunks: []string{"c-a"}},
+ {Name: "Shanghai", ID: "city-a", Chunks: []string{"c-a"}},
+ {Name: "Acme", ID: "acme-b", Chunks: []string{"c-b"}},
+ {Name: "Shanghai", ID: "city-b", Chunks: []string{"c-b"}},
+ },
+ Relation: []*types.GraphRelation{
+ {Node1: "Acme", Node2: "Shanghai", SourceID: "acme-a", TargetID: "city-a"},
+ {Node1: "Acme", Node2: "Shanghai", SourceID: "acme-b", TargetID: "city-b"},
+ {Node1: "Acme", Node2: "Shanghai", SourceID: "acme-a", TargetID: "city-b"},
+ {Node1: "Acme", Node2: "Shanghai"},
+ nil,
+ },
+ }
+ got := relationsBackedBy(graph, []*types.SearchResult{nil, {ID: "c-a"}})
+ require.Len(t, got, 1)
+ assert.Same(t, graph.Relation[0], got[0])
+}
diff --git a/internal/application/repository/retriever/neo4j/repository.go b/internal/application/repository/retriever/neo4j/repository.go
index b30c500dc..62027e479 100644
--- a/internal/application/repository/retriever/neo4j/repository.go
+++ b/internal/application/repository/retriever/neo4j/repository.go
@@ -194,37 +194,9 @@ func (n *Neo4jRepository) SearchNode(
return nil, fmt.Errorf("failed to run query: %v", err)
}
- graphData := &types.GraphData{}
- nodeSeen := make(map[string]bool)
- for result.Next(ctx) {
- record := result.Record()
- node, _ := record.Get("n")
- rel, _ := record.Get("r")
- targetNode, _ := record.Get("m")
-
- nodeData := node.(neo4j.Node)
- targetNodeData := targetNode.(neo4j.Node)
-
- // Convert node to types.Node
- for _, n := range []neo4j.Node{nodeData, targetNodeData} {
- nameStr := n.Props["name"].(string)
- if _, ok := nodeSeen[nameStr]; !ok {
- nodeSeen[nameStr] = true
- graphData.Node = append(graphData.Node, &types.GraphNode{
- Name: nameStr,
- Chunks: listI2listS(n.Props["chunks"].([]interface{})),
- Attributes: listI2listS(n.Props["attributes"].([]interface{})),
- })
- }
- }
-
- // Convert relationship to types.Relation
- relData := rel.(neo4j.Relationship)
- graphData.Relation = append(graphData.Relation, &types.GraphRelation{
- Node1: nodeData.Props["name"].(string),
- Node2: targetNodeData.Props["name"].(string),
- Type: relData.Type,
- })
+ graphData, err := decodeGraphSearchResult(ctx, result)
+ if err != nil {
+ return nil, err
}
// Make truncation visible. A silent cap reads as "the graph has no more
// matches" when in fact candidates were dropped.
@@ -250,6 +222,84 @@ func (n *Neo4jRepository) SearchNode(
return result.(*types.GraphData), nil
}
+// decodeGraphSearchResult keeps document instances distinct and restores the
+// stored direction even when the seed is the target of an undirected match.
+func decodeGraphSearchResult(ctx context.Context, result neo4j.Result) (*types.GraphData, error) {
+ graph := &types.GraphData{}
+ nodeSeen := make(map[string]*types.GraphNode)
+ relationSeen := make(map[string]bool)
+ for result.Next(ctx) {
+ record := result.Record()
+ if record == nil {
+ return nil, fmt.Errorf("graph query returned a nil record")
+ }
+ n, _, err := neo4j.GetRecordValue[neo4j.Node](record, "n")
+ if err != nil {
+ return nil, fmt.Errorf("failed to decode graph seed: %w", err)
+ }
+ m, _, err := neo4j.GetRecordValue[neo4j.Node](record, "m")
+ if err != nil {
+ return nil, fmt.Errorf("failed to decode graph neighbour: %w", err)
+ }
+ r, _, err := neo4j.GetRecordValue[neo4j.Relationship](record, "r")
+ if err != nil {
+ return nil, fmt.Errorf("failed to decode graph relationship: %w", err)
+ }
+ // Keep the matched seed first for evidence ranking, independently of direction.
+ for _, node := range []neo4j.Node{n, m} {
+ if nodeSeen[node.ElementId] != nil {
+ continue
+ }
+ decoded, err := decodeGraphNode(node)
+ if err != nil {
+ return nil, err
+ }
+ nodeSeen[node.ElementId] = decoded
+ graph.Node = append(graph.Node, decoded)
+ }
+ source, target := n, m
+ if r.StartElementId == m.ElementId && r.EndElementId == n.ElementId {
+ source, target = m, n
+ } else if r.StartElementId != n.ElementId || r.EndElementId != m.ElementId {
+ return nil, fmt.Errorf("graph relationship %q does not connect its returned endpoints", r.ElementId)
+ }
+ if r.ElementId == "" {
+ return nil, fmt.Errorf("graph relationship has no element identity")
+ }
+ if !relationSeen[r.ElementId] {
+ relationSeen[r.ElementId] = true
+ graph.Relation = append(graph.Relation, &types.GraphRelation{
+ Node1: nodeSeen[source.ElementId].Name, Node2: nodeSeen[target.ElementId].Name, Type: r.Type,
+ ID: r.ElementId, SourceID: source.ElementId, TargetID: target.ElementId,
+ })
+ }
+ }
+ if err := result.Err(); err != nil {
+ return nil, fmt.Errorf("failed to read graph query results: %w", err)
+ }
+ return graph, nil
+}
+
+func decodeGraphNode(node neo4j.Node) (*types.GraphNode, error) {
+ name, ok := node.Props["name"].(string)
+ if node.ElementId == "" || !ok || name == "" {
+ return nil, fmt.Errorf("graph node %q has no identity or name", node.ElementId)
+ }
+ chunks, ok := node.Props["chunks"].([]any)
+ if !ok && node.Props["chunks"] != nil {
+ return nil, fmt.Errorf("graph node %q has invalid chunks", node.ElementId)
+ }
+ attributes, ok := node.Props["attributes"].([]any)
+ if !ok && node.Props["attributes"] != nil {
+ return nil, fmt.Errorf("graph node %q has invalid attributes", node.ElementId)
+ }
+ knowledgeID, _ := node.Props["kg"].(string)
+ return &types.GraphNode{
+ Name: name, Chunks: listI2listS(chunks), Attributes: listI2listS(attributes),
+ ID: node.ElementId, KnowledgeID: knowledgeID,
+ }, nil
+}
+
// graphSearchCypher builds the bounded graph-search query and its parameters
// for one label expression and one set of entity names.
//
@@ -265,9 +315,13 @@ func (n *Neo4jRepository) SearchNode(
// - Exact name matches rank first, then the shortest names, then alphabetical
// order. Ordering by name alone lets an entity whose name *is* the query
// fall outside the cap once the substring matches exceed it.
-// - The same key is carried into both LIMITs, so a truncated result keeps the
+// - The seed order is carried into the row LIMIT, so a truncated result keeps the
// neighbourhoods of the highest-ranked seeds rather than an arbitrary
// subset of the rows.
+//
+// Each edge is expanded only from its earliest seed, so duplicate endpoint
+// matches cannot consume the row cap. Only the bounded seed list is collected;
+// grouping every candidate relationship would require unbounded working memory.
func graphSearchCypher(labelExpr string, nodes []string) (string, map[string]interface{}) {
query := `
MATCH (n:` + labelExpr + `)
@@ -277,11 +331,15 @@ func graphSearchCypher(labelExpr string, nodes []string) (string, map[string]int
CASE WHEN n.name IN $nodes THEN 0 ELSE 1 END AS seed_rank,
size(n.name) AS name_len,
n.name AS name
- ORDER BY seed_rank, name_len, name
+ ORDER BY seed_rank, name_len, name, n.kg, elementId(n)
LIMIT $maxSeedNodes
+ WITH collect(n) AS seeds
+ UNWIND range(0, size(seeds) - 1) AS seed_index
+ WITH seeds[seed_index] AS n, seeds[0..seed_index] AS earlier_seeds, seed_index
MATCH (n)-[r]-(m:` + labelExpr + `)
- WITH n, r, m, seed_rank, name_len, name
- ORDER BY seed_rank, name_len, name
+ WHERE NOT m IN earlier_seeds
+ WITH n, r, m, seed_index
+ ORDER BY seed_index, elementId(r)
LIMIT $maxRows
RETURN n, r, m
`
diff --git a/internal/application/repository/retriever/neo4j/repository_test.go b/internal/application/repository/retriever/neo4j/repository_test.go
index 829490e8d..21884cd5a 100644
--- a/internal/application/repository/retriever/neo4j/repository_test.go
+++ b/internal/application/repository/retriever/neo4j/repository_test.go
@@ -1,8 +1,14 @@
package neo4j
import (
+ "context"
+ "errors"
"strings"
"testing"
+
+ "github.com/neo4j/neo4j-go-driver/v6/neo4j"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
)
// TestGraphSearchCypherBoundsAndOrders pins the three review points on #3550:
@@ -16,6 +22,10 @@ func TestGraphSearchCypherBoundsAndOrders(t *testing.T) {
"EXISTS { (n)--() }",
"CASE WHEN n.name IN $nodes THEN 0 ELSE 1 END AS seed_rank",
"ORDER BY seed_rank, name_len, name",
+ "WITH collect(n) AS seeds",
+ "UNWIND range(0, size(seeds) - 1) AS seed_index",
+ "WHERE NOT m IN earlier_seeds",
+ "ORDER BY seed_index, elementId(r)",
"LIMIT $maxSeedNodes",
"LIMIT $maxRows",
} {
@@ -24,10 +34,16 @@ func TestGraphSearchCypherBoundsAndOrders(t *testing.T) {
}
}
- // The ordering key has to reach both caps: a row LIMIT without it keeps an
- // arbitrary subset of the rows.
- if got := strings.Count(query, "ORDER BY seed_rank, name_len, name"); got != 2 {
- t.Errorf("ORDER BY applied %d time(s), want 2 (seed cap and row cap):\n%s", got, query)
+ // Collect only the capped seeds, never the unbounded relationship candidates.
+ collectAt := strings.Index(query, "WITH collect(n) AS seeds")
+ if collectAt < strings.Index(query, "LIMIT $maxSeedNodes") || strings.Count(query, "collect(") != 1 {
+ t.Errorf("only the bounded seed list may be collected:\n%s", query)
+ }
+ if !strings.Contains(query, "name, n.kg, elementId(n)") {
+ t.Errorf("same-named document instances need stable tie breakers:\n%s", query)
+ }
+ if strings.Index(query, "WHERE NOT m IN earlier_seeds") > strings.Index(query, "LIMIT $maxRows") {
+ t.Errorf("duplicate endpoint matches must be removed before the row cap:\n%s", query)
}
if strings.Index(query, "LIMIT $maxSeedNodes") > strings.Index(query, "LIMIT $maxRows") {
t.Errorf("the seed cap must be applied before the row cap:\n%s", query)
@@ -56,3 +72,153 @@ func TestGraphSearchCypherBoundsAndOrders(t *testing.T) {
t.Errorf("label expression not applied to both matches:\n%s", query)
}
}
+
+type graphRecordResult struct {
+ neo4j.Result
+ records []*neo4j.Record
+ index int
+ err error
+}
+
+func (r *graphRecordResult) Next(context.Context) bool {
+ if r.index >= len(r.records) {
+ return false
+ }
+ r.index++
+ return true
+}
+
+func (r *graphRecordResult) Record() *neo4j.Record { return r.records[r.index-1] }
+func (r *graphRecordResult) Err() error { return r.err }
+
+func graphTestNode(id, name, document, chunk string, attributes ...string) neo4j.Node {
+ attrs := make([]any, len(attributes))
+ for i, attribute := range attributes {
+ attrs[i] = attribute
+ }
+ return neo4j.Node{ElementId: id, Props: map[string]any{
+ "name": name, "kg": document, "chunks": []any{chunk}, "attributes": attrs,
+ }}
+}
+
+func graphTestRecord(n, m neo4j.Node, r neo4j.Relationship) *neo4j.Record {
+ return &neo4j.Record{Keys: []string{"n", "r", "m"}, Values: []any{n, r, m}}
+}
+
+func TestDecodeGraphSearchDirectionAndIdentity(t *testing.T) {
+ a := graphTestNode("a", "Acme", "doc1", "c1")
+ b := graphTestNode("b", "Shanghai", "doc1", "c1")
+ r := neo4j.Relationship{ElementId: "r", StartElementId: "a", EndElementId: "b", Type: "LOCATED_IN"}
+ reverse := neo4j.Relationship{ElementId: "reverse", StartElementId: "b", EndElementId: "a", Type: "LOCATED_IN"}
+ self := neo4j.Relationship{ElementId: "self", StartElementId: "a", EndElementId: "a", Type: "RELATED_TO"}
+ for _, tt := range []struct {
+ name string
+ records []*neo4j.Record
+ nodeCount int
+ firstNode string
+ relations [][3]string
+ }{
+ {"outgoing", []*neo4j.Record{graphTestRecord(a, b, r)}, 2, "a", [][3]string{{"r", "a", "b"}}},
+ {"incoming", []*neo4j.Record{graphTestRecord(b, a, r)}, 2, "b", [][3]string{{"r", "a", "b"}}},
+ {
+ "both seeds",
+ []*neo4j.Record{graphTestRecord(b, a, r), graphTestRecord(a, b, r)},
+ 2, "b",
+ [][3]string{{"r", "a", "b"}},
+ },
+ {
+ "bidirectional",
+ []*neo4j.Record{graphTestRecord(a, b, r), graphTestRecord(a, b, reverse)},
+ 2, "a",
+ [][3]string{{"r", "a", "b"}, {"reverse", "b", "a"}},
+ },
+ {
+ "self loop",
+ []*neo4j.Record{graphTestRecord(a, a, self), graphTestRecord(a, a, self)},
+ 1, "a",
+ [][3]string{{"self", "a", "a"}},
+ },
+ } {
+ t.Run(tt.name, func(t *testing.T) {
+ graph, err := decodeGraphSearchResult(context.Background(), &graphRecordResult{records: tt.records})
+ require.NoError(t, err)
+ require.Len(t, graph.Node, tt.nodeCount)
+ assert.Equal(t, tt.firstNode, graph.Node[0].ID, "seed evidence priority must not change")
+ require.Len(t, graph.Relation, len(tt.relations))
+ for i, want := range tt.relations {
+ got := graph.Relation[i]
+ assert.Equal(t, want, [3]string{got.ID, got.SourceID, got.TargetID})
+ byID := map[string]string{"a": "Acme", "b": "Shanghai"}
+ assert.Equal(t, byID[want[1]], got.Node1)
+ assert.Equal(t, byID[want[2]], got.Node2)
+ }
+ })
+ }
+}
+
+func TestDecodeGraphSearchPreservesSameNamedDocumentSources(t *testing.T) {
+ a1 := graphTestNode("a1", "Acme", "doc1", "c1", "doc1 attribute")
+ b1 := graphTestNode("b1", "Shanghai", "doc1", "c1")
+ a2 := graphTestNode("a2", "Acme", "doc2", "c2", "doc2 attribute")
+ b2 := graphTestNode("b2", "Shanghai", "doc2", "c2")
+ r1 := neo4j.Relationship{ElementId: "r1", StartElementId: "a1", EndElementId: "b1", Type: "LOCATED_IN"}
+ r2 := neo4j.Relationship{ElementId: "r2", StartElementId: "a2", EndElementId: "b2", Type: "LOCATED_IN"}
+ for _, records := range [][]*neo4j.Record{
+ {graphTestRecord(b1, a1, r1), graphTestRecord(b2, a2, r2), graphTestRecord(a1, b1, r1)},
+ {graphTestRecord(b2, a2, r2), graphTestRecord(b1, a1, r1), graphTestRecord(a2, b2, r2)},
+ } {
+ graph, err := decodeGraphSearchResult(context.Background(), &graphRecordResult{records: records})
+ require.NoError(t, err)
+ require.Len(t, graph.Node, 4)
+ require.Len(t, graph.Relation, 2, "same names and type do not make two document edges identical")
+ var sources, attributes []string
+ for _, node := range graph.Node {
+ if node.Name == "Acme" {
+ sources = append(sources, node.KnowledgeID+":"+node.Chunks[0])
+ attributes = append(attributes, node.Attributes...)
+ }
+ }
+ assert.ElementsMatch(t, []string{"doc1:c1", "doc2:c2"}, sources)
+ assert.ElementsMatch(t, []string{"doc1 attribute", "doc2 attribute"}, attributes)
+ }
+}
+
+func TestDecodeGraphSearchReportsInvalidRecordsAndStreamErrors(t *testing.T) {
+ a := graphTestNode("a", "Acme", "doc", "c")
+ b := graphTestNode("b", "Shanghai", "doc", "c")
+ r := neo4j.Relationship{ElementId: "r", StartElementId: "a", EndElementId: "b", Type: "LOCATED_IN"}
+ streamErr := errors.New("stream interrupted")
+ graph, err := decodeGraphSearchResult(context.Background(), &graphRecordResult{
+ records: []*neo4j.Record{graphTestRecord(a, b, r)}, err: streamErr,
+ })
+ assert.Nil(t, graph, "a failed stream must not return a successful partial graph")
+ assert.ErrorIs(t, err, streamErr)
+
+ missingName := neo4j.Node{ElementId: "a", Props: map[string]any{}}
+ missingID := graphTestNode("", "Acme", "doc", "c")
+ wrongEndpoint := r
+ wrongEndpoint.EndElementId = "elsewhere"
+ missingRelationID := r
+ missingRelationID.ElementId = ""
+ for _, record := range []*neo4j.Record{
+ nil,
+ {Keys: []string{"n"}, Values: []any{"not a node"}},
+ graphTestRecord(missingName, b, r),
+ graphTestRecord(missingID, b, r),
+ graphTestRecord(a, b, wrongEndpoint),
+ graphTestRecord(a, b, missingRelationID),
+ } {
+ result := &graphRecordResult{records: []*neo4j.Record{record}}
+ graph, err := decodeGraphSearchResult(context.Background(), result)
+ assert.Error(t, err)
+ assert.Nil(t, graph)
+ }
+
+ // Optional properties may be absent in legacy graph data.
+ delete(a.Props, "attributes")
+ graph, err = decodeGraphSearchResult(context.Background(), &graphRecordResult{records: []*neo4j.Record{
+ graphTestRecord(a, b, r),
+ }})
+ require.NoError(t, err)
+ assert.Empty(t, graph.Node[0].Attributes)
+}
diff --git a/internal/application/repository/retriever/neo4j/search_integration_test.go b/internal/application/repository/retriever/neo4j/search_integration_test.go
new file mode 100644
index 000000000..f2f11da81
--- /dev/null
+++ b/internal/application/repository/retriever/neo4j/search_integration_test.go
@@ -0,0 +1,94 @@
+package neo4j
+
+import (
+ "context"
+ "fmt"
+ "os"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/neo4j/neo4j-go-driver/v6/neo4j"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// Run against a disposable Neo4j instance with authentication disabled:
+// Set WEKNORA_NEO4J_TEST_URI=bolt://127.0.0.1:7687, then run:
+// go test ./internal/application/repository/retriever/neo4j -run Integration
+func TestSearchNodeIntegration(t *testing.T) {
+ uri := os.Getenv("WEKNORA_NEO4J_TEST_URI")
+ if uri == "" {
+ t.Skip("set WEKNORA_NEO4J_TEST_URI to run the live Neo4j regression")
+ }
+ ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+ defer cancel()
+ driver, err := neo4j.NewDriver(uri, neo4j.NoAuth())
+ require.NoError(t, err)
+ t.Cleanup(func() { assert.NoError(t, driver.Close(context.Background())) })
+ require.NoError(t, driver.VerifyConnectivity(ctx))
+ repo := NewNeo4jRepository(driver).(*Neo4jRepository)
+ namespace := types.NameSpace{KnowledgeBase: fmt.Sprintf("graph_regression_%d", time.Now().UnixNano())}
+ label := repo.Label(namespace)
+ t.Cleanup(func() {
+ cleanupCtx, cleanupCancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cleanupCancel()
+ _, cleanupErr := neo4j.ExecuteQuery(cleanupCtx, driver, "MATCH (n:"+label+") DETACH DELETE n",
+ nil, neo4j.EagerResultTransformer)
+ assert.NoError(t, cleanupErr)
+ })
+ _, err = neo4j.ExecuteQuery(ctx, driver, `
+ CREATE (a1:`+label+` {name: 'Acme', kg: 'doc1', chunks: ['c1'], attributes: ['doc1 attribute']}),
+ (b1:`+label+` {name: 'Shanghai', kg: 'doc1', chunks: ['c1'], attributes: []}),
+ (a2:`+label+` {name: 'Acme', kg: 'doc2', chunks: ['c2'], attributes: ['doc2 attribute']}),
+ (b2:`+label+` {name: 'Shanghai', kg: 'doc2', chunks: ['c2'], attributes: []}),
+ (a1)-[:HEADQUARTERED_IN]->(b1), (a2)-[:HAS_BRANCH_IN]->(b2),
+ (b1)-[:RELATED_TO]->(a1), (a1)-[:SELF]->(a1)
+ `, nil, neo4j.EagerResultTransformer)
+ require.NoError(t, err)
+ t.Run("deduplicate before the row cap", func(t *testing.T) {
+ query, params := graphSearchCypher(label, []string{"Acme", "Shanghai"})
+ params["maxRows"] = 5 // Four stored edges; duplicate endpoint matches must not fill this fifth slot.
+ result, queryErr := neo4j.ExecuteQuery(ctx, driver, query, params, neo4j.EagerResultTransformer)
+ require.NoError(t, queryErr)
+ require.Len(t, result.Records, 4)
+ params["maxRows"] = 1
+ result, queryErr = neo4j.ExecuteQuery(ctx, driver, query, params, neo4j.EagerResultTransformer)
+ require.NoError(t, queryErr)
+ require.Len(t, result.Records, 1)
+ })
+ for _, seeds := range [][]string{{"Shanghai"}, {"Acme"}, {"Acme", "Shanghai"}} {
+ t.Run(fmt.Sprint(seeds), func(t *testing.T) {
+ graph, searchErr := repo.SearchNode(ctx, namespace, seeds)
+ require.NoError(t, searchErr)
+ require.Len(t, graph.Node, 4)
+ assert.Equal(t, seeds[0], graph.Node[0].Name, "the best seed still supplies evidence first")
+ var sources, attributes []string
+ for _, node := range graph.Node {
+ if node.Name == "Acme" {
+ sources = append(sources, node.KnowledgeID+":"+node.Chunks[0])
+ attributes = append(attributes, node.Attributes...)
+ }
+ }
+ assert.ElementsMatch(t, []string{"doc1:c1", "doc2:c2"}, sources)
+ assert.ElementsMatch(t, []string{"doc1 attribute", "doc2 attribute"}, attributes)
+ wantRelations := 4
+ if len(seeds) == 1 && seeds[0] == "Shanghai" {
+ wantRelations = 3 // The self-loop has no Shanghai endpoint.
+ }
+ require.Len(t, graph.Relation, wantRelations)
+ for _, relation := range graph.Relation {
+ switch relation.Type {
+ case "HEADQUARTERED_IN", "HAS_BRANCH_IN":
+ assert.Equal(t, "Acme", relation.Node1)
+ assert.Equal(t, "Shanghai", relation.Node2)
+ case "RELATED_TO":
+ assert.Equal(t, "Shanghai", relation.Node1)
+ assert.Equal(t, "Acme", relation.Node2)
+ case "SELF":
+ assert.Equal(t, relation.SourceID, relation.TargetID)
+ }
+ }
+ })
+ }
+}
diff --git a/internal/types/extract_graph.go b/internal/types/extract_graph.go
index 019c88325..9cce3a6d6 100644
--- a/internal/types/extract_graph.go
+++ b/internal/types/extract_graph.go
@@ -19,6 +19,9 @@ type GraphNode struct {
Name string `json:"name,omitempty"`
Chunks []string `json:"chunks,omitempty"`
Attributes []string `json:"attributes,omitempty"`
+ // Retrieval identities are local to the graph query, not extraction configuration.
+ ID string `json:"-" yaml:"-"`
+ KnowledgeID string `json:"-" yaml:"-"`
}
// GraphRelation represents the relation of the graph
@@ -26,6 +29,10 @@ type GraphRelation struct {
Node1 string `json:"node1,omitempty"`
Node2 string `json:"node2,omitempty"`
Type string `json:"type,omitempty"`
+ // Names are for display; these identities link to the actual document instances.
+ ID string `json:"-" yaml:"-"`
+ SourceID string `json:"-" yaml:"-"`
+ TargetID string `json:"-" yaml:"-"`
}
type GraphData struct {
diff --git a/internal/types/extract_graph_test.go b/internal/types/extract_graph_test.go
new file mode 100644
index 000000000..130129571
--- /dev/null
+++ b/internal/types/extract_graph_test.go
@@ -0,0 +1,32 @@
+package types
+
+import (
+ "encoding/json"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+ "gopkg.in/yaml.v3"
+)
+
+func TestGraphRetrievalIdentitiesDoNotChangeExtractionSerialization(t *testing.T) {
+ graph := GraphData{
+ Node: []*GraphNode{{Name: "Acme", Chunks: []string{"c1"}, ID: "private-node", KnowledgeID: "private-doc"}},
+ Relation: []*GraphRelation{{
+ Node1: "Acme", Node2: "Shanghai", Type: "LOCATED_IN",
+ ID: "private-relation", SourceID: "private-node", TargetID: "private-target",
+ }},
+ }
+ for _, marshal := range []func(any) ([]byte, error){json.Marshal, yaml.Marshal} {
+ data, err := marshal(graph)
+ require.NoError(t, err)
+ assert.Contains(t, string(data), "Acme")
+ assert.NotContains(t, string(data), "private-", "retrieval IDs must not leak into prompts or saved examples")
+ }
+ var parsed GraphData
+ err := json.Unmarshal([]byte(`{"node":[{"name":"Acme","ID":"model-id"}],
+ "relation":[{"node1":"Acme","node2":"Shanghai","SourceID":"model-id"}]}`), &parsed)
+ require.NoError(t, err)
+ assert.Empty(t, parsed.Node[0].ID)
+ assert.Empty(t, parsed.Relation[0].SourceID, "extraction JSON cannot supply database identities")
+}