Querying

FlowRAG combines vector search with knowledge graph traversal for richer results than either approach alone.

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

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

In hybrid, local, and global modes, FlowRAG runs two retrieval paths:

1. Vector search — finds semantically similar chunks via embeddings
2. 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

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 Services

Path Finding

Find the shortest path between two entities:

const path = await rag.findPath('ServiceA', 'ServiceB');
// ServiceA → Kafka → ServiceB

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

await rag.search('query', { limit: 20 });

Statistics

const stats = await rag.stats();
// { documents: 50, chunks: 320, entities: 85, relations: 120, vectors: 320 }

Export

Export the knowledge graph in multiple formats:

await rag.export('json'); // Entities + relations as JSON
await rag.export('csv');  // Relation table (source, type, target, description)
await rag.export('dot');  // Graphviz digraph

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.