Repository files navigation

Version: 0.1.0

Type: Tool

The Neo4j Query Plugin is a secure and efficient integration tool that connects Dify.ai with Neo4j graph databases. It enables powerful graph-based data exploration, querying, and manipulation within Dify workflows and AI agents. The plugin supports both Neo4j Aura cloud instances and locally hosted Neo4j deployments.

• Parameterized queries - Prevents Cypher injection attacks
• Preflight validation - EXPLAIN-based query validation before execution
• Write query protection - Optional write operations with explicit user consent
• Query length limits - Maximum 2000 characters per query
• Resource limits - Configurable maximum record limits (default: 1000)

• Singleton driver pattern - Efficient connection reuse
• Streaming results - Memory-efficient record fetching with configurable fetch_size
• Connection pooling - Built-in Neo4j driver connection management
• User agent tracking - Identifies plugin traffic in Neo4j logs

• Multi-database support - Query different databases within the same instance
• Read/Write control - Granular control over query capabilities
• Both cloud and local - Works with Neo4j Aura and self-hosted instances
• Parameterized queries - Safe value substitution in Cypher queries

• ✨Write query protection with explicit checkbox and warnings
• ✨Preflight EXPLAIN checks for syntax validation and query type detection
• ✨Database parameter for multi-database support
• ✨Configurable record limits with efficient streaming
• ✨User agent identification for tracking plugin usage
• ✨Improved error messages with detailed validation feedback
• ✨Thread-safe driver management with proper cleanup
• ✨Better credential validation with specific error messages
• 🔧 Renamed credentials from "Aura" to "Neo4j" for clarity
• 🔧 Optimized memory usage with itertools.islice
• 🔧 Enhanced parameter documentation with examples

• Dify instance (self-hosted or cloud)
• Neo4j database (Aura or self-hosted)
• Dify Plugin Development Scaffold (CLI)

1. Install Dify Plugin CLI

   # Follow instructions from Dify documentation# https://docs.dify.ai/plugin-dev-en/0211-getting-started-dify-tool

2. Package the Plugin

   # Navigate to parent folder of dify_neo4j./dify plugin package dify_neo4j

3. Upload to Dify

   • Go to your Dify instance
   • Navigate to Plugins tab
   • Upload the packaged plugin

4. Configure Credentials

   • Neo4j URL: Your connection URL (e.g.,neo4j+s://xxxxx.databases.neo4j.io orbolt://localhost:7687)
   • Neo4j Username: Your database username
   • Neo4j Password: Your database password

5. Use in Workflows

   • Add as a tool node in workflows
   • Configure as a tool for AI agents

{"query":"MATCH (p:Person) RETURN p.name, p.age LIMIT 10","parameters": {}}

{"query":"MATCH (p:Person {name: $name}) RETURN p","parameters": {"name":"Alice"}}

{"query":"MATCH (n:Node) RETURN n LIMIT 5","database":"movies"}

{"query":"CREATE (p:Person {name: $name, age: $age}) RETURN p","parameters": {"name":"Bob","age":30},"allow_write_queries":true}

When using the plugin with AI agents, provide the graph schema as context:

Provide your LLM with:- Node labels and their properties- Relationship types- Constraints and indexes

For complex queries on large graphs:

1. First query: Extract relevant subgraph
2. Second query: Execute detailed analysis on the subgraph

# ✅GOOD-ParameterizedMATCH (p:Person{name: $name})RETURNp# ❌BAD-StringconcatenationMATCH (p:Person{name:'Alice'})RETURNp

• Keepallow_write_queries disabled by default
• Only enable when necessary
• Review queries before execution
• Test on non-production databases first

SeeSECURITY.md for comprehensive security documentation including:

• Query validation mechanisms
• Write protection details
• Preflight checks
• Parameter handling
• Best practices

This plugin:

• ✅ Sends queries only to your specified Neo4j instance
• ✅ Does not store or transmit data to third parties
• ✅ Credentials are securely stored in Dify
• ✅ All data remains within your Neo4j infrastructure

• Nikola Milosevic