feat(falkordb): install FalkorDB
This commit is contained in:
Masaki Yatsu
255
falkordb/README.md
Normal file
255
falkordb/README.md
Normal file
@@ -0,0 +1,255 @@
|
||||
# FalkorDB
|
||||
|
||||
FalkorDB is a high-performance graph database with vector similarity search capabilities, designed for knowledge graphs and GraphRAG applications. It uses OpenCypher as its query language and is Redis-compatible.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Installation](#installation)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Connection Information](#connection-information)
|
||||
- [Usage](#usage)
|
||||
- [Configuration](#configuration)
|
||||
- [Cognee Integration](#cognee-integration)
|
||||
- [Management](#management)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Installation
|
||||
|
||||
Install FalkorDB with interactive configuration:
|
||||
|
||||
```bash
|
||||
just falkordb::install
|
||||
```
|
||||
|
||||
This will:
|
||||
|
||||
- Create the `falkordb` namespace with Pod Security Standards (baseline)
|
||||
- Generate and store a password in Vault (or Kubernetes Secret)
|
||||
- Deploy FalkorDB using the custom Helm chart
|
||||
- Optionally enable Prometheus monitoring
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Kubernetes cluster with Longhorn storage
|
||||
- For secret management: Vault and External Secrets Operator (optional but recommended)
|
||||
- For monitoring: kube-prometheus-stack (optional)
|
||||
|
||||
## Connection Information
|
||||
|
||||
| Property | Value |
|
||||
| -------- | ------------------------------------- |
|
||||
| Host | `falkordb.falkordb.svc.cluster.local` |
|
||||
| Port | `6379` |
|
||||
| Protocol | Redis (Bolt not supported) |
|
||||
|
||||
## Usage
|
||||
|
||||
### Get Password
|
||||
|
||||
```bash
|
||||
just falkordb::get-password
|
||||
```
|
||||
|
||||
### Health Check
|
||||
|
||||
Requires [telepresence](https://www.telepresence.io/) connection:
|
||||
|
||||
```bash
|
||||
telepresence connect
|
||||
just falkordb::health-check
|
||||
```
|
||||
|
||||
### Test Graph Operations
|
||||
|
||||
Run a basic test that creates nodes, relationships, and queries:
|
||||
|
||||
```bash
|
||||
just falkordb::test
|
||||
```
|
||||
|
||||
### Redis CLI
|
||||
|
||||
Connect directly using redis-cli:
|
||||
|
||||
```bash
|
||||
PASSWORD=$(just falkordb::get-password)
|
||||
redis-cli -h falkordb.falkordb.svc.cluster.local -p 6379 -a "$PASSWORD"
|
||||
```
|
||||
|
||||
### Cypher Queries
|
||||
|
||||
FalkorDB uses OpenCypher query language via Redis commands:
|
||||
|
||||
```bash
|
||||
# Create a node
|
||||
redis-cli -a "$PASSWORD" GRAPH.QUERY mygraph "CREATE (:Person {name: 'Alice', age: 30})"
|
||||
|
||||
# Create a relationship
|
||||
redis-cli -a "$PASSWORD" GRAPH.QUERY mygraph \
|
||||
"MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}) CREATE (a)-[:KNOWS]->(b)"
|
||||
|
||||
# Query the graph
|
||||
redis-cli -a "$PASSWORD" GRAPH.QUERY mygraph \
|
||||
"MATCH (p:Person)-[:KNOWS]->(friend) RETURN p.name, friend.name"
|
||||
|
||||
# Delete a graph
|
||||
redis-cli -a "$PASSWORD" GRAPH.DELETE mygraph
|
||||
```
|
||||
|
||||
### Python Client
|
||||
|
||||
```python
|
||||
from falkordb import FalkorDB
|
||||
|
||||
db = FalkorDB(
|
||||
host='falkordb.falkordb.svc.cluster.local',
|
||||
port=6379,
|
||||
password='<password>'
|
||||
)
|
||||
graph = db.select_graph('knowledge')
|
||||
|
||||
# Create nodes
|
||||
graph.query("CREATE (:Concept {name: 'Machine Learning'})")
|
||||
graph.query("CREATE (:Concept {name: 'Neural Networks'})")
|
||||
|
||||
# Create relationship
|
||||
graph.query("""
|
||||
MATCH (a:Concept {name: 'Neural Networks'}), (b:Concept {name: 'Machine Learning'})
|
||||
CREATE (a)-[:PART_OF]->(b)
|
||||
""")
|
||||
|
||||
# Query
|
||||
result = graph.query("MATCH (c:Concept) RETURN c.name")
|
||||
for record in result.result_set:
|
||||
print(record)
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ---------------------- | ----------- | ----------------------- |
|
||||
| `FALKORDB_NAMESPACE` | `falkordb` | Kubernetes namespace |
|
||||
| `FALKORDB_VERSION` | `v4.14.8` | FalkorDB image version |
|
||||
| `FALKORDB_STORAGE_SIZE`| `8Gi` | Persistent volume size |
|
||||
|
||||
### Pod Security Standards
|
||||
|
||||
The namespace is configured with:
|
||||
|
||||
- `enforce=baseline` - Required for FalkorDB (runs as root)
|
||||
- `warn=restricted` - Shows warnings for restricted violations
|
||||
|
||||
## Cognee Integration
|
||||
|
||||
FalkorDB can serve as both graph and vector store for [Cognee](https://github.com/topoteretes/cognee), enabling knowledge graph construction and RAG without separate vector database.
|
||||
|
||||
### Configuration
|
||||
|
||||
```bash
|
||||
# .env for Cognee
|
||||
GRAPH_DATABASE_PROVIDER=falkordb
|
||||
GRAPH_DATABASE_URL=falkordb.falkordb.svc.cluster.local
|
||||
GRAPH_DATABASE_PORT=6379
|
||||
|
||||
VECTOR_DB_PROVIDER=falkordb
|
||||
VECTOR_DB_URL=falkordb.falkordb.svc.cluster.local
|
||||
VECTOR_DB_PORT=6379
|
||||
```
|
||||
|
||||
### Usage with Cognee
|
||||
|
||||
```python
|
||||
import cognee
|
||||
|
||||
# Add documents
|
||||
await cognee.add("documents/", dataset_name="knowledge_base")
|
||||
|
||||
# Generate knowledge graph (automatic)
|
||||
await cognee.cognify()
|
||||
|
||||
# Search with RAG
|
||||
results = await cognee.search("What is the relationship between X and Y?")
|
||||
```
|
||||
|
||||
## Management
|
||||
|
||||
### Uninstall
|
||||
|
||||
```bash
|
||||
just falkordb::uninstall
|
||||
```
|
||||
|
||||
### Cleanup Vault Secrets
|
||||
|
||||
```bash
|
||||
just falkordb::cleanup
|
||||
```
|
||||
|
||||
### Available Commands
|
||||
|
||||
```bash
|
||||
just falkordb # List all commands
|
||||
just falkordb::install # Install FalkorDB
|
||||
just falkordb::uninstall # Uninstall FalkorDB
|
||||
just falkordb::get-password # Get password
|
||||
just falkordb::health-check # Check health (requires telepresence)
|
||||
just falkordb::test # Run graph operation tests
|
||||
just falkordb::cleanup # Clean up Vault secrets
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Pod Not Starting
|
||||
|
||||
Check pod status and logs:
|
||||
|
||||
```bash
|
||||
kubectl get pods -n falkordb
|
||||
kubectl logs falkordb-0 -n falkordb
|
||||
kubectl describe pod falkordb-0 -n falkordb
|
||||
```
|
||||
|
||||
### Authentication Issues
|
||||
|
||||
Verify password is correctly configured:
|
||||
|
||||
```bash
|
||||
# Check secret exists
|
||||
kubectl get secret falkordb-password -n falkordb
|
||||
|
||||
# Test authentication from within cluster
|
||||
kubectl exec falkordb-0 -n falkordb -- redis-cli -a "$PASSWORD" PING
|
||||
```
|
||||
|
||||
### Connection Refused
|
||||
|
||||
Ensure service is running:
|
||||
|
||||
```bash
|
||||
kubectl get svc -n falkordb
|
||||
```
|
||||
|
||||
For external access, use telepresence or port-forward:
|
||||
|
||||
```bash
|
||||
kubectl port-forward svc/falkordb -n falkordb 6379:6379
|
||||
```
|
||||
|
||||
### Memory Issues
|
||||
|
||||
FalkorDB stores graphs in memory. Monitor usage:
|
||||
|
||||
```bash
|
||||
kubectl top pod -n falkordb
|
||||
```
|
||||
|
||||
If running out of memory, increase limits in `falkordb-values.gomplate.yaml`.
|
||||
|
||||
## References
|
||||
|
||||
- [FalkorDB Documentation](https://docs.falkordb.com/)
|
||||
- [FalkorDB GitHub](https://github.com/FalkorDB/FalkorDB)
|
||||
- [OpenCypher Query Language](https://opencypher.org/)
|
||||
- [Cognee Documentation](https://docs.cognee.ai/)
|
||||
Reference in New Issue
Block a user