@falkordb/langchain-ts

FalkorDB integration for LangChain.js - A blazing fast graph database for AI applications.

About

FalkorDB is a high-performance graph database that enables you to build knowledge graphs and perform complex graph queries with blazing speed. This package provides seamless integration between FalkorDB and LangChain.js, allowing you to leverage graph-based knowledge for your AI applications.

Features

• 🚀 Fast Graph Queries: Built on Redis with optimized graph operations
• 🔗 Cypher Support: Use Cypher query language for graph operations
• 🧠 LLM Integration: Works seamlessly with LangChain's QA chains
• 📊 Schema Management: Automatic schema detection and updates
• 🔄 Async/Await: Modern async API
• 📝 TypeScript: Full TypeScript support with type definitions

Installation

npm install @falkordb/langchain-ts falkordb

You'll also need LangChain and a language model:

npm install langchain @langchain/openai @langchain/community

Quick Start

1. Start FalkorDB

The easiest way to run FalkorDB is with Docker:

docker run -p 6379:6379 -it --rm falkordb/falkordb:latest

2. Basic Usage

import { FalkorDBGraph } from "@falkordb/langchain-ts";
import { OpenAI } from "@langchain/openai";
import { GraphCypherQAChain } from "@langchain/community/chains/graph_qa/cypher";

// Initialize connection
const graph = await FalkorDBGraph.initialize({
  host: "localhost",
  port: 6379,
  graph: "movies"
});

// Create some data
await graph.query(
  "CREATE (a:Actor {name:'Bruce Willis'})" +
  "-[:ACTED_IN]->(:Movie {title: 'Pulp Fiction'})"
);

// Refresh schema
await graph.refreshSchema();

// Set up QA chain
const model = new OpenAI({ temperature: 0 });
// Note: Type assertion needed for LangChain compatibility
const chain = GraphCypherQAChain.fromLLM({
  llm: model,
  graph: graph as any,
});

// Ask questions about your graph
const response = await chain.run("Who played in Pulp Fiction?");
console.log(response);
// Output: Bruce Willis played in Pulp Fiction.

// Clean up
await graph.close();

3. Advanced Connection Options

The library supports multiple ways to connect to FalkorDB:

Using a URL

// Simple URL connection
const graph = await FalkorDBGraph.initialize({
  url: "falkor://localhost:6379",
  graph: "movies"
});

// URL with authentication
const graph = await FalkorDBGraph.initialize({
  url: "falkor://username:password@myserver:6379",
  graph: "movies"
});

Using a Pre-initialized Driver

This is useful when you need full control over the driver configuration or want to share a driver across multiple graph instances:

import { FalkorDB } from "falkordb";

// Create a driver with custom configuration
const driver = await FalkorDB.connect({
  socket: { 
    host: "localhost", 
    port: 6379,
    connectTimeout: 10000
  },
  username: "myuser",
  password: "mypassword",
  poolOptions: {
    min: 2,
    max: 10
  }
});

// Use the driver with multiple graphs
const moviesGraph = await FalkorDBGraph.initialize({
  driver: driver,
  graph: "movies"
});

const booksGraph = await FalkorDBGraph.initialize({
  driver: driver,
  graph: "books"
});

// Close graphs (won't close the shared driver)
await moviesGraph.close();
await booksGraph.close();

// Close the driver when done
await driver.close();

API Reference

FalkorDBGraph

initialize(config: FalkorDBGraphConfig): Promise<FalkorDBGraph>

Creates and initializes a new FalkorDB connection.

Config Options:

• host (string, optional): Database host. Default: "localhost" (ignored if url or driver is provided)
• port (number, optional): Database port. Default: 6379 (ignored if url or driver is provided)
• graph (string, optional): Graph name to use
• url (string, optional): Connection URL format: falkor[s]://[[username][:password]@][host][:port][/db-number]. Takes precedence over host and port
• username (string, optional): Username for authentication
• password (string, optional): Password for authentication
• driver (FalkorDB, optional): Pre-initialized FalkorDB driver instance. When provided, all other connection options are ignored
• enhancedSchema (boolean, optional): Enable enhanced schema details. Default: false

Examples:

Using host and port:

const graph = await FalkorDBGraph.initialize({
  host: "localhost",
  port: 6379,
  graph: "myGraph",
  enhancedSchema: true
});

Using connection URL:

const graph = await FalkorDBGraph.initialize({
  url: "falkor://localhost:6379",
  graph: "myGraph"
});

Using connection URL with authentication:

const graph = await FalkorDBGraph.initialize({
  url: "falkor://username:password@localhost:6379",
  graph: "myGraph"
});

Using a pre-initialized driver:

import { FalkorDB } from "falkordb";

const driver = await FalkorDB.connect({
  socket: { host: "localhost", port: 6379 },
  username: "myuser",
  password: "mypassword"
});

const graph = await FalkorDBGraph.initialize({
  driver: driver,
  graph: "myGraph"
});

// When using a pre-initialized driver, you're responsible for closing it
await graph.close(); // This won't close the driver
await driver.close(); // Close the driver manually

query(query: string): Promise<any>

Executes a Cypher query on the graph.

const result = await graph.query(
  "MATCH (n:Person) RETURN n.name LIMIT 10"
);

refreshSchema(): Promise<void>

Updates the graph schema information.

await graph.refreshSchema();
console.log(graph.getSchema());

getSchema(): string

Returns the current graph schema as a formatted string.

getStructuredSchema(): StructuredSchema

Returns the structured schema object containing node properties, relationship properties, and relationships.

selectGraph(graphName: string): Promise<void>

Switches to a different graph.

await graph.selectGraph("anotherGraph");

close(): Promise<void>

Closes the database connection.

await graph.close();

Advanced Usage

Custom Cypher Queries

const graph = await FalkorDBGraph.initialize({
  host: "localhost",
  port: 6379,
  graph: "movies"
});

// Complex query
const result = await graph.query(`
  MATCH (a:Actor)-[:ACTED_IN]->(m:Movie)
  WHERE m.year > 2000
  RETURN a.name, m.title, m.year
  ORDER BY m.year DESC
  LIMIT 10
`);

console.log(result.data);

Multiple Queries

await graph.executeQueries([
  "CREATE (p:Person {name: 'Alice'})",
  "CREATE (p:Person {name: 'Bob'})",
  "MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}) CREATE (a)-[:KNOWS]->(b)"
]);

Working with Schema

await graph.refreshSchema();

// Get formatted schema
const schema = graph.getSchema();
console.log(schema);

// Get structured schema
const structuredSchema = graph.getStructuredSchema();
console.log(structuredSchema.nodeProps);
console.log(structuredSchema.relationships);

Error Handling

try {
  const graph = await FalkorDBGraph.initialize({
    host: "localhost",
    port: 6379,
    graph: "myGraph"
  });
  
  await graph.query("CREATE (n:Node {name: 'test'})");
  
} catch (error) {
  console.error("Error:", error.message);
} finally {
  await graph.close();
}

Examples

Check out the examples directory for more use cases:

• Basic Queries - Basic graph operations
• Graph DB FalkorDB - Working with FalkorDB
• Quickstart - Quick start guide

Requirements

• Node.js >= 18
• FalkorDB server running (Redis-compatible)
• LangChain >= 0.1.0

Development

# Clone the repository
git clone https://github.com/FalkorDB/FalkorDB-Langchain-js.git
cd FalkorDB-Langchain-js

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run integration tests (requires FalkorDB running)
npm run test:int

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Documentation

• FalkorDB Documentation
• LangChain Documentation
• Cypher Query Language

License

MIT © FalkorDB

Support

• 📫 GitHub Issues
• 💬 FalkorDB Discord
• 📧 Email: [email protected]
• 🌐 Website: https://www.falkordb.com/

Acknowledgments

Special thanks to the LangChain team for their excellent framework and the FalkorDB team for their amazing graph database.