Querying
FlowRAG combines vector search with knowledge graph traversal for richer results than either approach alone.
Basic Search
Section titled “Basic Search”const results = await rag.search('how does authentication work');Each result contains:
interface SearchResult { id: string; // chunk ID content: string; // chunk text score: number; // relevance score source: 'vector' | 'graph'; sources: Source[]; // citation / provenance metadata?: Record<string, unknown>; // includes document metadata fields}
interface Source { documentId: string; filePath?: string; chunkIndex: number;}Query Modes
Section titled “Query Modes”await rag.search('query', { mode: 'hybrid' }); // default| Mode | Strategy | Best For |
|---|---|---|
hybrid |
Vector + graph combined | General queries (default) |
local |
Focus on specific entities in query | “What does ServiceA do?” |
global |
High-level concepts and themes | “How does the system handle payments?” |
naive |
Vector search only, no graph | Simple similarity search |
Dual Retrieval
Section titled “Dual Retrieval”In hybrid, local, and global modes, FlowRAG runs two retrieval paths:
- Vector search — finds semantically similar chunks via embeddings
- Graph traversal — identifies entities in the query, then follows their relationships to find connected context
Results are merged, deduplicated, and scored using configurable weights:
const rag = createFlowRAG({ schema, ...createLocalStorage('./data'), options: { querying: { defaultMode: 'hybrid', maxResults: 10, vectorWeight: 0.7, // 70% weight to vector results graphWeight: 0.3, // 30% weight to graph results }, },});Data Flow Tracing
Section titled “Data Flow Tracing”Trace how data flows through your system:
// Where does this data go?const downstream = await rag.traceDataFlow('user-event', 'downstream');// user-event → Kafka → Analytics → Dashboard
// Where does this data come from?const upstream = await rag.traceDataFlow('dashboard-metric', 'upstream');// Dashboard ← Analytics ← Kafka ← Multiple ServicesPath Finding
Section titled “Path Finding”Find the shortest path between two entities:
const path = await rag.findPath('ServiceA', 'ServiceB');// ServiceA → Kafka → ServiceBEntity Search
Section titled “Entity Search”Search entities semantically by description similarity, rather than exact name matching:
const results = await rag.searchEntities('the service that handles login');// Returns: [{ entity: { name: 'Auth Service', type: 'SERVICE', ... }, score: 0.92 }]Filter by entity type:
const services = await rag.searchEntities('payment processing', { type: 'SERVICE', limit: 5 });Limiting Results
Section titled “Limiting Results”await rag.search('query', { limit: 20 });Statistics
Section titled “Statistics”const stats = await rag.stats();// { documents: 50, chunks: 320, entities: 85, relations: 120, vectors: 320 }Export
Section titled “Export”Export the knowledge graph in multiple formats:
await rag.export('json'); // Entities + relations as JSONawait rag.export('csv'); // Relation table (source, type, target, description)await rag.export('dot'); // Graphviz digraphEvaluation
Section titled “Evaluation”If an Evaluator is configured, run quality metrics on search results:
const rag = createFlowRAG({ schema, ...createLocalStorage('./data'), evaluator: myEvaluator, // implements Evaluator interface});
const result = await rag.evaluate('how does auth work', { reference: 'expected answer' });// result.scores: { precision: 0.85, recall: 0.72, faithfulness: 0.91 }The evaluate method runs a search internally and passes results to the evaluator. See Interfaces for the Evaluator interface.