Graph backend (Neo4j & FalkorDB)

​

Overview

Experio stores the knowledge graph (ontology instances, document relationships, embeddings on graph nodes) against either Neo4j or FalkorDB. Exactly one backend is active per deployment. The application routes reads and writes through a shared abstraction layer so ingestion, chat retrieval, and admin tools stay consistent.

​

Choosing the active backend

Set GRAPH_PROVIDER to neo4j or falkordb in Admin > Settings > System Settings (DB category). Connection fields for the inactive provider remain stored but are ignored until you switch. See the DB settings reference for all keys. After changing provider or connection details, validate connectivity using the dashboard flow (including the reachability probe surfaced when switching providers).

​

Graph migration (staff)

Staff can copy data between backends from Admin > Settings > Graph migration:

• Neo4j → FalkorDB and FalkorDB → Neo4j jobs stream progress over a WebSocket.
• Use prerequisites on that page (backup, connectivity) before starting a long run.

Product and engineering decisions for the reverse direction are documented in FalkorDB → Neo4j migration research.

​

Behavioral differences

​

Omnistrate / cluster deployment

Both Neo4j and FalkorDB run as internal cluster services with manual scale-to-zero. They are independent of platform boot — server, workers, and initdb no longer wait for a graph DB to be healthy.

​

Default state

Seeded connection defaults (via initdb → seed_config):

• FALKOR_URI: redis://falkordb:6379 (cluster internal DNS)
• NEO4J_URI: neo4j://neo4j:7687

Passwords come from Omnistrate secrets neo4jPassword and falkordbPassword. See Omnistrate deployment.

​

Controlling graph DB replicas

Use Django admin ServiceConfiguration (same UI as JupyterLab scale-to-zero):

• keep_alive — maintain 1 replica (use for the active provider)
• keep_down — maintain 0 replicas (use for the inactive provider to save cost)
• auto — manual strategy defaults to 1 replica; prefer explicit modes above

Changes are applied by the scale-to-zero sidecar on the server pod (polls every ~60s). Allow a few minutes after toggling before expecting connectivity.

​

Migration window (both providers up)

Graph migration requires both backends reachable:

1. Set neo4j and falkordb to keep_alive in ServiceConfiguration
2. Wait until both pass connectivity checks (Admin → System Settings → provider probe, or inspect /health/ — graph may show checks.neo4j unhealthy until warm)
3. Run migration from Admin → Settings → Graph migration
4. Switch GRAPH_PROVIDER in System Settings
5. Set the inactive backend to keep_down

​

Health monitoring

GET /health/ reports the active graph provider under checks.neo4j (legacy key name; includes provider: neo4j | falkordb). Graph downtime does not fail the whole endpoint:

• status: degraded — platform OK, graph unavailable (expected during scale-to-zero)
• status: unhealthy — Postgres, Redis, RabbitMQ, or LLM failed

Chat and graph ingestion need the active provider up; other admin features may work while status is degraded.

​

Schema cache

On server startup a background thread pre-warms the graph schema cache in Redis (24h TTL). If the graph is down at boot, warming fails softly and the first chat query may be slower until cache is populated. With neo4j on keep_alive, this is rarely an issue in steady state. For how relationship attributes interact with graph introspection on Neo4j, see Relationship attributes.

​

Local development

When using the devcontainer, FalkorDB and its Browser UI are available for ad-hoc Cypher. See FalkorDB Browser (local development).