Skip to content

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

fix(compilation): make graph search Enter on an entity name highlight the node instead of rendering the whole graph (#19320)

euvrecfb599a67c34
diff --git a/web/src/components/structure-graph/adapters.test.ts b/web/src/components/structure-graph/adapters.test.ts
new file mode 100644
index 0000000000..0b999e664c
--- /dev/null
+++ b/web/src/components/structure-graph/adapters.test.ts
@@ -0,0 +1,29 @@
+import { findEntityDisplayNameByKeyword } from './adapters';
+
+describe('findEntityDisplayNameByKeyword', () => {
+ const entities = [
+ { id: 'e1', name: 'swallow' },
+ { id: 'e2', name: 'Swan', aliases: ['swan lake', ' SWAN '] },
+ { id: 'e3', name: 'owl tree' },
+ ];
+
+ it('matches an entity name case-insensitively and returns its canonical name', () => {
+ expect(findEntityDisplayNameByKeyword(entities, 'swallow')).toBe('swallow');
+ expect(findEntityDisplayNameByKeyword(entities, ' SWALLOW ')).toBe(
+ 'swallow',
+ );
+ });
+
+ it('matches an alias and returns the canonical entity name', () => {
+ expect(findEntityDisplayNameByKeyword(entities, 'swan lake')).toBe('Swan');
+ expect(findEntityDisplayNameByKeyword(entities, 'swan')).toBe('Swan');
+ });
+
+ it('returns an empty string for partial matches, unknown or empty keywords', () => {
+ expect(findEntityDisplayNameByKeyword(entities, 'swal')).toBe('');
+ expect(findEntityDisplayNameByKeyword(entities, 'tree')).toBe('');
+ expect(findEntityDisplayNameByKeyword(entities, 'unknown')).toBe('');
+ expect(findEntityDisplayNameByKeyword(entities, '')).toBe('');
+ expect(findEntityDisplayNameByKeyword([], 'swallow')).toBe('');
+ });
+});
diff --git a/web/src/components/structure-graph/adapters.ts b/web/src/components/structure-graph/adapters.ts
index e64c8e6029..65f74efa8d 100644
--- a/web/src/components/structure-graph/adapters.ts
+++ b/web/src/components/structure-graph/adapters.ts
@@ -37,6 +37,29 @@ export function getEntityDisplayName(entity: IStructureGraphEntity) {
return trim(entity.name ?? entity.id ?? '');
}
+// Exact (case-insensitive) entity name/alias hit for a typed search keyword.
+// Returns the canonical display name so callers can treat the keyword like a
+// dropdown selection (highlight + dim); '' when the keyword only partially
+// matches or names nothing, in which case the server-side keyword subgraph
+// search stays the right fallback.
+export function findEntityDisplayNameByKeyword(
+ entities: IStructureGraphEntity[],
+ keyword: string,
+) {
+ const query = keyword.trim().toLowerCase();
+ if (!query) {
+ return '';
+ }
+ const entity = (entities ?? []).find(
+ (item) =>
+ getEntityDisplayName(item).toLowerCase() === query ||
+ (item.aliases ?? []).some(
+ (alias) => (alias ?? '').trim().toLowerCase() === query,
+ ),
+ );
+ return entity ? getEntityDisplayName(entity) : '';
+}
+
function normalizeEntity(entity: IStructureGraphEntity) {
const id = entity.id ?? entity.name ?? '';
const name = getEntityDisplayName(entity);
@@ -172,18 +195,20 @@ export function adaptTreeToTreeData(
export function adaptKnowledgeGraphToForceGraph(
template: IStructureGraphTemplate,
): IArtifactGraph {
- const entities: IArtifactGraphEntity[] = (template.entities ?? []).map((entity) => {
- const normalized = normalizeEntity(entity);
- return {
- slug: normalized.id,
- name: normalized.name,
- aliases: normalized.aliases ?? [],
- description: getEntityDescription(normalized),
- type: normalized.type ?? '',
- weight: normalized.mention_count ?? 0,
- source_chunk_ids: normalized.source_chunk_ids,
- };
- });
+ const entities: IArtifactGraphEntity[] = (template.entities ?? []).map(
+ (entity) => {
+ const normalized = normalizeEntity(entity);
+ return {
+ slug: normalized.id,
+ name: normalized.name,
+ aliases: normalized.aliases ?? [],
+ description: getEntityDescription(normalized),
+ type: normalized.type ?? '',
+ weight: normalized.mention_count ?? 0,
+ source_chunk_ids: normalized.source_chunk_ids,
+ };
+ },
+ );
const entityNames = new Set(entities.map((entity) => entity.slug));
diff --git a/web/src/pages/chunk/representation/hooks/use-graph-entity-search.test.ts b/web/src/pages/chunk/representation/hooks/use-graph-entity-search.test.ts
new file mode 100644
index 0000000000..3d5963d10a
--- /dev/null
+++ b/web/src/pages/chunk/representation/hooks/use-graph-entity-search.test.ts
@@ -0,0 +1,90 @@
+import { useFetchDocumentStructureGraph } from '@/hooks/use-document-request';
+import { act, renderHook } from '@testing-library/react';
+import { useGraphEntitySearch } from './use-graph-entity-search';
+
+jest.mock('@/hooks/use-document-request', () => ({
+ useFetchDocumentStructureGraph: jest.fn(),
+}));
+
+const mockFetchDocumentStructureGraph = jest.mocked(
+ useFetchDocumentStructureGraph,
+);
+
+function setupHook(entities: Array<Record<string, unknown>>) {
+ mockFetchDocumentStructureGraph.mockReturnValue({
+ data: {
+ templates: [
+ {
+ template_id: 't1',
+ template_name: 'Graph',
+ kind: 'knowledge_graph',
+ entities,
+ relations: [],
+ },
+ ],
+ },
+ loading: false,
+ } as never);
+
+ return renderHook(() => useGraphEntitySearch());
+}
+
+describe('useGraphEntitySearch handleNoMatchEnter', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('treats Enter on an existing entity name like a dropdown selection: highlight + dim, no keyword refetch', () => {
+ const { result } = setupHook([
+ { id: 'e1', name: 'swallow' },
+ { id: 'e2', name: 'owl tree' },
+ ]);
+
+ act(() => {
+ result.current.handleNoMatchEnter('swallow');
+ });
+
+ expect(result.current.highlightNodeId).toBe('swallow');
+ expect(result.current.graphSelectValue).toBe('swallow');
+ // The keyword subgraph refetch must NOT be armed for a name hit.
+ expect(mockFetchDocumentStructureGraph).toHaveBeenLastCalledWith('');
+ });
+
+ it('matches entity names case-insensitively and returns the canonical name', () => {
+ const { result } = setupHook([
+ { id: 'e1', name: 'Swan', aliases: ['swan lake'] },
+ ]);
+
+ act(() => {
+ result.current.handleNoMatchEnter(' SWAN ');
+ });
+
+ expect(result.current.highlightNodeId).toBe('Swan');
+ });
+
+ it('matches an alias and highlights the owning entity', () => {
+ const { result } = setupHook([
+ { id: 'e1', name: 'Swan', aliases: ['swan lake'] },
+ ]);
+
+ act(() => {
+ result.current.handleNoMatchEnter('swan lake');
+ });
+
+ expect(result.current.highlightNodeId).toBe('Swan');
+ });
+
+ it('falls back to the server-side keyword search for text that names no entity', () => {
+ const { result } = setupHook([{ id: 'e1', name: 'swallow' }]);
+
+ act(() => {
+ result.current.handleNoMatchEnter('something else');
+ });
+
+ expect(result.current.highlightNodeId).toBeNull();
+ expect(result.current.graphSelectValue).toBe('something else');
+ expect(mockFetchDocumentStructureGraph).toHaveBeenLastCalledWith(
+ 'something else',
+ );
+ });
+});
diff --git a/web/src/pages/chunk/representation/hooks/use-graph-entity-search.ts b/web/src/pages/chunk/representation/hooks/use-graph-entity-search.ts
index 7b39df3b09..de2fa645fb 100644
--- a/web/src/pages/chunk/representation/hooks/use-graph-entity-search.ts
+++ b/web/src/pages/chunk/representation/hooks/use-graph-entity-search.ts
@@ -1,5 +1,8 @@
import { type SelectWithSearchFlagOptionType } from '@/components/originui/select-with-search';
-import { getEntityDisplayName } from '@/components/structure-graph/adapters';
+import {
+ findEntityDisplayNameByKeyword,
+ getEntityDisplayName,
+} from '@/components/structure-graph/adapters';
import { type ClickableNode } from '@/components/structure-graph/representation-renderer';
import { CompilationTemplateKind } from '@/constants/compilation';
import { useFetchDocumentStructureGraph } from '@/hooks/use-document-request';
@@ -76,11 +79,26 @@ export function useGraphEntitySearch(
[selectedTemplate?.entities, onNodeClick],
);
- const handleNoMatchEnter = useCallback((keywords: string) => {
- setGraphKeywords(keywords);
- setSearchKeyword('');
- setSelectedNodeId('');
- }, []);
+ const handleNoMatchEnter = useCallback(
+ (keywords: string) => {
+ // Enter on a keyword that exactly names an entity must behave like
+ // picking it from the dropdown: highlight that node and its neighbors
+ // and dim the rest. Only unmatched text falls back to the server-side
+ // keyword subgraph, which renders fully bright.
+ const entityName = findEntityDisplayNameByKeyword(
+ selectedTemplate?.entities ?? [],
+ keywords,
+ );
+ if (entityName) {
+ handleSelectEntity(entityName);
+ return;
+ }
+ setGraphKeywords(keywords);
+ setSearchKeyword('');
+ setSelectedNodeId('');
+ },
+ [selectedTemplate?.entities, handleSelectEntity],
+ );
const handleSearchKeywordChange = useCallback((value: string) => {
setSearchKeyword(value);
diff --git a/web/src/pages/dataset/compilation/dataset-structure-view.tsx b/web/src/pages/dataset/compilation/dataset-structure-view.tsx
index ce4477ccf5..9c70cd63b4 100644
--- a/web/src/pages/dataset/compilation/dataset-structure-view.tsx
+++ b/web/src/pages/dataset/compilation/dataset-structure-view.tsx
@@ -3,7 +3,10 @@ import {
SelectWithSearchFlagOptionType,
} from '@/components/originui/select-with-search';
import { ConfirmDeleteDialog } from '@/components/confirm-delete-dialog';
-import { getEntityDisplayName } from '@/components/structure-graph/adapters';
+import {
+ findEntityDisplayNameByKeyword,
+ getEntityDisplayName,
+} from '@/components/structure-graph/adapters';
import { RepresentationRenderer } from '@/components/structure-graph/representation-renderer';
import { Button } from '@/components/ui/button';
import { Card } from '@/components/ui/card';
@@ -112,10 +115,25 @@ export function DatasetStructureView({ kind }: DatasetStructureViewProps) {
setSelectedNodeId(name);
}, []);
- const handleNoMatchEnter = useCallback((keywords: string) => {
- setGraphKeywords(keywords);
- setSelectedNodeId('');
- }, []);
+ const handleNoMatchEnter = useCallback(
+ (keywords: string) => {
+ // Enter on a keyword that exactly names an entity must behave like
+ // picking it from the dropdown: highlight that node and its neighbors
+ // and dim the rest. Only unmatched text falls back to the server-side
+ // keyword subgraph, which renders fully bright.
+ const entityName = findEntityDisplayNameByKeyword(
+ template?.entities ?? [],
+ keywords,
+ );
+ if (entityName) {
+ handleSelectEntity(entityName);
+ return;
+ }
+ setGraphKeywords(keywords);
+ setSelectedNodeId('');
+ },
+ [template?.entities, handleSelectEntity],
+ );
const handleDeleteStructure = useCallback(async () => {
const code = await deleteDatasetStructure(kind);