Skip to main content
Neo4j is a graph database that stores data as nodes, relationships, and properties instead of tables or documents. This structure allows you to organize your data in an intuitive way, similar to sketching ideas on a whiteboard. With SambaNova, you can power Neo4j applications with state-of-the-art language models for enhanced graph analytics and natural language queries.
This guide was tested with Neo4j 5.x and the SambaNova GraphRAG codebase v1.x. If you’re using different versions, some steps may vary.

​
Overview

This guide walks you through building a GraphRAG application using agents powered by SambaNova LLMs and Neo4j. GraphRAG is a structured, hierarchical approach to Retrieval Augmented Generation (RAG) that leverages graph relationships rather than plain text snippets. The sample application retrieves electronic health records for patients in the Synthea dataset. The agents use Neo4j’s graph query language (Cypher) to access records through two methods:
  • Static queries: Pre-defined Cypher queries for common operations.
  • Dynamic queries: LLM-generated Cypher queries based on natural language input (text-to-Cypher).

​
Prerequisites

  • A SambaCloud account and API key, or SambaStack deployment.
  • Python 3.11 or later.
  • UV package manager for Python dependency management.
  • Neo4j database instance (local or cloud-hosted).

​
Setup

​
Install dependencies

  1. Install the UV package manager. 
    pip install uv
  2. Clone the integrations repository and navigate to the project directory. 
    git clone git@github.com:sambanova/integrations.git
cd integrations/langgraph/agentic_graph_rag
  3. Create a virtual environment and install dependencies. 
    uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

​
Load the Synthea dataset

  1. Download the Synthea dataset dump file.
  2. Load the dump file into your Neo4j instance. For Neo4j Desktop:
    1. Stop the database.
    2. Open the terminal for your database.
    3. Run the following command, replacing the path with your download location: 
      neo4j-admin database load --from-path=/path/to/dump synthea --overwrite-destination
    4. Start the database.
For Neo4j Aura or other cloud instances, refer to the Neo4j data import documentation.

​
Configure environment variables

  1. Copy the example environment file. 
    cp .env.example .env
  2. Edit .env and set the following variables: 
    # SambaNova API configuration
SAMBANOVA_API_KEY=your_api_key_here
SAMBANOVA_BASE_URL=https://api.sambanova.ai/v1

# Neo4j connection
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password_here

​
Run the application

​
Start the backend

Launch the HTTP server that connects to the Neo4j database using SambaNova LLMs. 
bash ./start_server.sh
You should see output indicating the server is running: 
INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete.

​
Open the frontend

Open your browser to the application landing page: 
http://localhost:8000/app

​
Verify the connection

  1. In the chatbot interface, enter a test query such as “List all patients.”
  2. Confirm that the application returns patient records from the Neo4j database.

​
Capabilities

Once configured, the GraphRAG application enables:
  • Natural language queries: Ask questions about patient data in plain English.
  • Graph traversal: Explore relationships between patients, conditions, medications, and encounters.
  • Text-to-Cypher: Automatically generate Cypher queries from natural language input.
  • Healthcare analytics: Analyze patterns across the Synthea dataset using graph-based insights.

​
Video demonstration

The following video demonstrates the GraphRAG application leveraging SambaNova LLMs to access healthcare data from a Neo4j database.

​
Troubleshooting

IssueSolution
Connection refused when starting backendVerify Neo4j is running and the NEO4J_URI in .env is correct.
Authentication errorsCheck that NEO4J_USERNAME and NEO4J_PASSWORD match your Neo4j credentials.
SAMBANOVA_API_KEY not set errorEnsure your .env file exists and contains a valid API key from SambaCloud.
Empty query resultsConfirm the Synthea dataset was loaded correctly. Run MATCH (n) RETURN count(n) in Neo4j Browser to verify data exists.
ModuleNotFoundErrorEnsure you activated the virtual environment: source .venv/bin/activate

​
More information