createGraph()

The createGraph() function is the main factory for creating a Graph instance.

Signature

function createGraph<TProvider extends GraphProvider>(
  options: CreateGraphOptions<TProvider>
): Graph

Parameters

options: CreateGraphOptions<TProvider>

Configuration object for creating the graph.

interface CreateGraphOptions<TProvider extends GraphProvider> {
  model: LanguageModel;
  embedding: EmbeddingModel;
  provider?: TProvider;
  cheapModel?: LanguageModel;
  storage?: StorageConfig;
  domain?: string;
  exampleQueries?: string[];
  chunking?: ChunkingConfig;
  namespace?: string;
}

Required Fields

model: LanguageModel

The language model used for generating answers and entity extraction. Must be a model from the Vercel AI SDK.

import { openai } from "@ai-sdk/openai";

model: openai("gpt-4o-mini")

Common options:

• openai("gpt-4o") - Most capable
• openai("gpt-4o-mini") - Best balance of cost/performance (recommended)
• anthropic("claude-3-5-sonnet-20241022") - Anthropic's best model
• google("gemini-1.5-pro") - Google's multimodal model

embedding: EmbeddingModel

The embedding model used for vector representations. Must be an embedding model from the Vercel AI SDK.

import { openai } from "@ai-sdk/openai";

embedding: openai.embedding("text-embedding-3-small")

Common options:

• openai.embedding("text-embedding-3-small") - 1536 dimensions, cheap (recommended)
• openai.embedding("text-embedding-3-large") - 3072 dimensions, better quality
• openai.embedding("text-embedding-ada-002") - Legacy model

Optional Fields

provider?: TProvider

The graph RAG algorithm provider. Determines how the graph is built and queried.

Default: lightrag() (when available)

import { lightrag } from "@graphrag-js/lightrag";
import { microsoftGraph } from "@graphrag-js/microsoft";
import { fastGraph } from "@graphrag-js/fast";
import { awsGraph } from "@graphrag-js/aws";
import { similarityGraph } from "@graphrag-js/similarity";

// LightRAG (default, balanced)
provider: lightrag()

// Microsoft GraphRAG (community detection)
provider: microsoftGraph()

// Fast GraphRAG (PageRank)
provider: fastGraph()

// AWS GraphRAG (fact-centric)
provider: awsGraph()

// Similarity Graph (simple baseline)
provider: similarityGraph()

See GraphProvider for details on each provider.

cheapModel?: LanguageModel

An optional cheaper model for summarization and other non-critical tasks. This can reduce costs significantly.

cheapModel: openai("gpt-4o-mini")

If not provided, the main model is used for all tasks.

storage?: StorageConfig

Storage backend configuration. Can specify different backends for graph, vector, and key-value stores.

interface StorageConfig {
  graph?: GraphStore;
  vector?: VectorStore;
  kv?: KVStore;
}

Default: In-memory storage for all three stores.

Examples:

import { memoryStorage } from "@graphrag-js/memory";

// All in-memory (default)
storage: memoryStorage()

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

// Mixed storage backends
storage: {
  graph: neo4jGraph({ url: "bolt://localhost:7687", username: "neo4j", password: "password" }),
  vector: qdrantVector({ url: "http://localhost:6333" }),
  kv: redisKV({ host: "localhost", port: 6379 }),
}

See Storage Interfaces for all storage options.

domain?: string

Optional natural language description of your data domain. Helps the LLM optimize entity extraction.

domain: "Scientific research papers on climate change"

When to use:

• Specialized or technical domains
• Domain-specific entity types
• Better extraction accuracy needed

exampleQueries?: string[]

Optional example queries that users might ask. Helps the LLM understand your use case and optimize extraction.

exampleQueries: [
  "What organizations lead climate research?",
  "What are the key findings on carbon emissions?",
  "How does deforestation affect global warming?",
]

When to use:

• Known query patterns
• Specialized query types
• Better retrieval accuracy needed

chunking?: ChunkingConfig

Configuration for document chunking.

interface ChunkingConfig {
  size?: number;
  overlap?: number;
  fn?: (text: string) => Chunk[];
}

Default:

chunking: {
  size: 1200,    // tokens
  overlap: 100,  // tokens
}

Custom chunking:

chunking: {
  fn: (text: string) => {
    // Your custom chunking logic
    return chunks.map((content, index) => ({
      id: `chunk-${index}`,
      content,
      metadata: {},
    }));
  },
}

Chunking strategies:

• Small chunks (500-800): Better precision, more nodes
• Large chunks (1200-1500): Better context, fewer nodes
• Overlap: 10-15% of chunk size for continuity

namespace?: string

Optional namespace for multi-tenancy. Isolates data in shared storage backends.

namespace: "project-alpha"

When to use:

• Multiple projects sharing storage
• Testing vs. production separation
• User-specific graphs in a multi-tenant app

Return Value

Returns a Graph instance with the following methods:

• insert() - Add documents to the graph
• query() - Query the graph with natural language
• entities - Entity operations
• relations - Relationship operations
• export() - Export the graph
• close() - Clean up resources

Examples

Minimal Example

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

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

Production Example

import { createGraph } from "@graphrag-js/core";
import { lightrag } from "@graphrag-js/lightrag";
import { neo4jGraph } from "@graphrag-js/neo4j";
import { qdrantVector } from "@graphrag-js/qdrant";
import { redisKV } from "@graphrag-js/redis";
import { openai } from "@ai-sdk/openai";

const graph = createGraph({
  // Models
  model: openai("gpt-4o-mini"),
  cheapModel: openai("gpt-4o-mini"),
  embedding: openai.embedding("text-embedding-3-small"),

  // Provider
  provider: lightrag({
    entityTypes: ["person", "organization", "location", "product"],
    maxGleanings: 1,
  }),

  // Storage
  storage: {
    graph: neo4jGraph({
      url: process.env.NEO4J_URL,
      username: process.env.NEO4J_USER,
      password: process.env.NEO4J_PASSWORD,
    }),
    vector: qdrantVector({
      url: process.env.QDRANT_URL,
      apiKey: process.env.QDRANT_API_KEY,
      collectionName: "embeddings",
    }),
    kv: redisKV({
      host: process.env.REDIS_HOST,
      port: parseInt(process.env.REDIS_PORT),
      password: process.env.REDIS_PASSWORD,
    }),
  },

  // Context
  domain: "E-commerce product catalog and customer reviews",
  exampleQueries: [
    "What products are most popular?",
    "What do customers say about quality?",
  ],

  // Chunking
  chunking: {
    size: 1000,
    overlap: 100,
  },

  // Multi-tenancy
  namespace: "prod-v1",
});

Domain-Specific Example

import { createGraph } from "@graphrag-js/core";
import { microsoftGraph } from "@graphrag-js/microsoft";
import { memoryStorage } from "@graphrag-js/memory";
import { anthropic } from "@ai-sdk/anthropic";

const graph = createGraph({
  model: anthropic("claude-3-5-sonnet-20241022"),
  embedding: openai.embedding("text-embedding-3-small"),

  provider: microsoftGraph({
    entityTypes: ["gene", "protein", "disease", "drug", "pathway"],
    graphClusterAlgorithm: "leiden",
    communityReportMaxTokens: 2000,
  }),

  storage: memoryStorage(),

  domain: "Biomedical research papers on cancer genomics",
  exampleQueries: [
    "Which genes are implicated in breast cancer?",
    "What drugs target the EGFR pathway?",
    "How does TP53 mutation affect treatment?",
  ],
});

Type Inference

TypeScript automatically infers the provider type, giving you type-safe query parameters:

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

const graph = createGraph({
  model: openai("gpt-4o-mini"),
  embedding: openai.embedding("text-embedding-3-small"),
  provider: lightrag(),  // TypeScript knows this is LightRAG
});

// Type-safe query parameters
await graph.query("question", {
  mode: "hybrid",  // ✅ TypeScript knows "hybrid" is valid
  // mode: "invalid",  // ❌ TypeScript error
});

Error Handling

try {
  const graph = createGraph({
    model: openai("gpt-4o-mini"),
    embedding: openai.embedding("text-embedding-3-small"),
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error("Invalid configuration:", error.message);
  } else {
    console.error("Failed to create graph:", error);
  }
}

See Also

• Graph Class - Graph instance methods
• GraphProvider - Provider interface and implementations
• Storage Interfaces - Storage backend options