Quick Start

Get up and running with GraphRAG.js in 5 minutes.

Installation

Install the core package, an algorithm, storage, and an AI SDK provider:

pnpm add @graphrag-js/core @graphrag-js/similarity @graphrag-js/memory ai @ai-sdk/openai

Basic Example

Create a simple graph RAG system using the similarity graph algorithm:

import { createGraph } from "@graphrag-js/core";
import { similarityGraph } from "@graphrag-js/similarity";
import { memoryStorage } from "@graphrag-js/memory";
import { openai } from "@ai-sdk/openai";

// Create the graph
const graph = createGraph({
  model: openai("gpt-4o-mini"),
  embedding: openai.embedding("text-embedding-3-small"),
  provider: similarityGraph(),
  storage: memoryStorage(),
});

// Insert documents
await graph.insert(`
  GraphRAG.js is a TypeScript library for building graph-enhanced RAG systems.
  It supports multiple algorithms including LightRAG, Microsoft GraphRAG, and more.
`);

// Query the graph
const { text } = await graph.query("What is GraphRAG.js?");
console.log(text);

Step-by-Step Walkthrough

1. Import Dependencies

import { createGraph } from "@graphrag-js/core";
import { similarityGraph } from "@graphrag-js/similarity";
import { memoryStorage } from "@graphrag-js/memory";
import { openai } from "@ai-sdk/openai";

2. Configure Your Graph

const graph = createGraph({
  // LLM for generating answers
  model: openai("gpt-4o-mini"),

  // Embedding model for vector search
  embedding: openai.embedding("text-embedding-3-small"),

  // Graph algorithm (similarity, lightrag, microsoft, fast, aws)
  provider: similarityGraph({
    similarityThreshold: 0.7,  // cosine similarity threshold for edges
  }),

  // Storage backend (memory, neo4j, qdrant, etc.)
  storage: memoryStorage(),
});

3. Insert Documents

Insert text documents to build the knowledge graph:

// Single document
await graph.insert("Your text content...");

// Multiple documents
await graph.insert([
  "Document 1...",
  "Document 2...",
  "Document 3...",
]);

// With metadata
await graph.insert({
  content: "Document content...",
  metadata: {
    source: "https://example.com",
    author: "John Doe",
    date: "2024-01-01",
  },
});

4. Query the Graph

Query your knowledge graph with natural language questions:

// Simple query
const { text } = await graph.query("What is GraphRAG.js?");
console.log(text);

// With options
const result = await graph.query("What algorithms are supported?", {
  maxDepth: 2,    // graph traversal depth
  topK: 10,       // number of initial results
});

// Streaming response
const { textStream } = await graph.query("Explain the architecture", {
  stream: true,
});

for await (const chunk of textStream) {
  process.stdout.write(chunk);
}

5. Get Context Only

Retrieve context without generating an answer:

const { context } = await graph.query("Your question", {
  contextOnly: true,
});

console.log(context);
// Use context with your own LLM pipeline

Using Different Algorithms

Switch algorithms by changing the provider:

LightRAG (Recommended)

Dual-level entity and relationship retrieval:

import { lightrag } from "@graphrag-js/lightrag";

const graph = createGraph({
  model: openai("gpt-4o-mini"),
  embedding: openai.embedding("text-embedding-3-small"),
  provider: lightrag({
    entityTypes: ["person", "organization", "location"],
    maxGleanings: 1,
  }),
  storage: memoryStorage(),
});

// Query with different modes
await graph.query("Question", { mode: "local" });    // entity-focused
await graph.query("Question", { mode: "global" });   // relationship-focused
await graph.query("Question", { mode: "hybrid" });   // combined (default)

Microsoft GraphRAG

Community detection with hierarchical reports:

import { microsoftGraph } from "@graphrag-js/microsoft";

const graph = createGraph({
  model: openai("gpt-4o-mini"),
  embedding: openai.embedding("text-embedding-3-small"),
  provider: microsoftGraph({
    graphClusterAlgorithm: "leiden",
    maxGraphClusterSize: 10,
  }),
  storage: memoryStorage(),
});

// Local: entity neighborhoods + community context
await graph.query("Specific question", { mode: "local" });

// Global: high-level community reports
await graph.query("Broad question", { mode: "global" });

Working with External Storage

For production use, connect to external databases:

Neo4j

import { neo4jGraph } from "@graphrag-js/neo4j";
import { qdrantVector } from "@graphrag-js/qdrant";
import { redisKV } from "@graphrag-js/redis";

const graph = createGraph({
  model: openai("gpt-4o-mini"),
  embedding: openai.embedding("text-embedding-3-small"),
  provider: lightrag(),
  storage: {
    graph: neo4jGraph({
      url: "bolt://localhost:7687",
      username: "neo4j",
      password: "password",
    }),
    vector: qdrantVector({
      url: "http://localhost:6333",
      collectionName: "my-vectors",
    }),
    kv: redisKV({
      host: "localhost",
      port: 6379,
    }),
  },
});

Entity and Relation Operations

Access entities and relationships directly:

// Get all entities
const entities = await graph.entities.list();

// Get specific entity
const entity = await graph.entities.get("entity-id");

// Get all relations
const relations = await graph.relations.list();

// Get relations for an entity
const entityRelations = await graph.relations.list({
  entityId: "entity-id",
});

Export Graph

Export your graph in different formats:

// GraphML format (Neo4j, Gephi, etc.)
const graphml = await graph.export("graphml");

// JSON format
const json = await graph.export("json");

// CSV format
const csv = await graph.export("csv");

Clean Up

Close the graph when done:

await graph.close();

Next Steps

• Core Concepts - Understand the architecture
• Algorithms - Deep dive into each algorithm
• API Reference - Complete API documentation
• Storage - Configure storage backends