Skip to main content

FalkorDB Browser

FalkorDB Browser is a web-based GUI for visualizing nodes, relationships, and running Cypher queries against the GospeLib graph database.

URLhttp://localhost:3004
Port3004
Imagefalkordb/falkordb-browser:latest
Profileobservability

Starting FalkorDB Browser​

FalkorDB Browser runs under the observability Docker Compose profile. It is not started by default.

# Start the full observability stack (Grafana, Alloy, Loki, Prometheus, FalkorDB Browser, etc.)
pnpm infra:observability

# Or start it manually with docker compose
docker compose -f infra/docker/compose.yml -f infra/docker/compose.dev.yml \
  --profile observability up -d

The browser waits for FalkorDB (port 6379) to be healthy before starting.

Connecting to the Graph​

Once FalkorDB Browser is running at http://localhost:3004:

  1. Open the browser and you should see a connection/login form.
  2. Enter the connection details:
    • Host: falkordb (the Docker service name — not localhost)
    • Port: 6379
    • Username: (leave blank)
    • Password: (leave blank)
  3. After connecting, select the gospelib graph from the graph dropdown.
Use falkordb, not localhost

FalkorDB Browser runs inside a Docker container. From inside the container, localhost refers to the container itself — not your host machine. You must use the Docker Compose service name falkordb as the host. Using localhost will fail with "Invalid credentials please recheck username and password."

No credentials required

The local dev FalkorDB instance has no requirepass set. Leave username and password empty. The NEXTAUTH_SECRET in the compose file is for the browser app's own session management, not for database access.

Useful Cypher Queries​

Count all nodes by label​

MATCH (n)
RETURN labels(n)[0] AS label, count(n) AS count
ORDER BY count DESC

Browse passages for a book​

MATCH (p:Passage)
WHERE p.book_id = 'gen'
RETURN p.id, p.chapter, p.verse, LEFT(p.text, 80) AS preview
ORDER BY p.chapter, p.verse
LIMIT 50

Explore a passage's full subgraph​

MATCH (p:Passage {id: 'gen.1.1'})-[r]-(connected)
RETURN p, r, connected

Find cross-references for a passage​

MATCH (p:Passage {id: 'gen.1.1'})-[:CROSS_REF]->(ref:Passage)
RETURN ref.id, ref.book_id, ref.chapter, ref.verse, LEFT(ref.text, 80) AS preview

Visualize a topic and its cited passages​

MATCH (t:IndexTopic {id: 'tg:faith'})-[:CITES]->(p:Passage)
RETURN t, p
LIMIT 25

Inspect interlinear word data​

MATCH (p:Passage {id: 'gen.1.1'})-[:HAS_WORD]->(w:WordAlignment)-[:DEFINED_BY]->(l:LexiconEntry)
RETURN w.order, w.token, w.gloss, l.strongs_id, l.lemma
ORDER BY w.order

Graph statistics summary​

CALL db.labels()
CALL db.relationshipTypes()

Verifying Ingest Results​

After running the ingest pipeline, use FalkorDB Browser to verify the data loaded correctly:

  1. Run the node count query above — compare counts against expected totals.
  2. Pick a few passages and check their cross-references and word alignments.
  3. Verify edge types exist with CALL db.relationshipTypes().

Troubleshooting​

ProblemSolution
"Invalid credentials" on loginUse falkordb as the host, not localhost — the browser runs inside Docker and can't reach the host network at localhost
Browser won't startCheck that FalkorDB is healthy: docker exec docker-falkordb-1 redis-cli PING
"No graphs found"Run the ingest pipeline first — the gospelib graph is created during ingest
Connection refused on 3004Ensure you started with --profile observability
Slow queriesFalkorDB Browser has no query timeout — avoid unbounded MATCH (n)-[r]-(m) without LIMIT