codenuk_backend_mine/services/multi-document-upload-service/NEO4J_DIAGNOSTIC_QUERIES.md

Neo4j Diagnostic Queries

Issue: No relationships found in Neo4j

If you're seeing "(no changes, no records)" when querying for CAUSES relationships, here are diagnostic queries to check what's actually in the database.

Diagnostic Queries

1. Check if any nodes exist

MATCH (n)
RETURN count(n) as node_count
LIMIT 1

2. Check if Concept nodes exist

MATCH (n:Concept)
RETURN count(n) as concept_count, 
       collect(DISTINCT labels(n)) as labels,
       collect(DISTINCT keys(n)) as properties
LIMIT 10

3. Check all relationship types

CALL db.relationshipTypes() YIELD relationshipType
RETURN relationshipType

4. Check all node labels

CALL db.labels() YIELD label
RETURN label

5. Check all relationships (any type)

MATCH (n)-[r]->(m)
RETURN type(r) as relationship_type, 
       count(r) as count,
       labels(n) as from_labels,
       labels(m) as to_labels
LIMIT 50

6. Check for CAUSES relationships specifically

MATCH (n)-[r:CAUSES]->(m)
RETURN n, r, m
LIMIT 50

7. Check for relationships with lowercase "causes"

MATCH (n)-[r]->(m)
WHERE type(r) =~ '(?i)causes'
RETURN type(r) as relationship_type, n, r, m
LIMIT 50

8. Check all nodes and their relationships

MATCH (n)
OPTIONAL MATCH (n)-[r]->(m)
RETURN n, labels(n) as node_labels, 
       type(r) as relationship_type, 
       m, labels(m) as target_labels
LIMIT 50

9. Check for nodes created by the service (by job_id property)

MATCH (n)-[r]->(m)
WHERE r.job_id IS NOT NULL
RETURN n, r, m, r.job_id as job_id
LIMIT 50

10. Check database statistics

MATCH (n)
RETURN count(n) as total_nodes,
       size([(n)-[r]->() | r]) as total_relationships

Common Issues and Solutions

Issue 1: No nodes at all

Symptom: Query 1 returns 0 nodes Cause: Service hasn't written anything to Neo4j, or connection failed Solution:

• Check service logs: docker-compose logs multi-document-upload-service
• Verify Neo4j connection in service configuration
• Check if job completed with 0 relations (extraction failed)

Issue 2: Nodes exist but no relationships

Symptom: Query 1 returns nodes, but Query 6 returns no relationships Cause: Relationships weren't created, or different relationship type Solution:

• Check Query 5 to see what relationship types actually exist
• Check service logs for graph writing errors
• Verify the job actually extracted relations (check job status)

Issue 3: Different relationship type

Symptom: Query 5 shows relationships but not CAUSES Cause: Service might be using a different relationship type Solution:

• Check Query 3 to see all relationship types
• Update query to use the correct relationship type

Issue 4: Different node labels

Symptom: Query 6 returns no results, but Query 2 shows different labels Cause: Service might be using different node labels Solution:

• Check Query 2 to see what labels exist
• Update query to match actual labels

Expected Structure

After a successful upload, you should see:

Nodes

• Label: Concept
• Properties: name, lastSeen

Relationships

• Type: CAUSES
• Properties: confidence, explanation, source_file_id, source_snippet, job_id, model, updated_at

Example Query

MATCH (cause:Concept)-[r:CAUSES]->(effect:Concept)
RETURN cause.name as cause, 
       effect.name as effect, 
       r.confidence as confidence,
       r.job_id as job_id,
       r.source_file_id as source_file
LIMIT 50

Troubleshooting Steps

1. Check service logs:

   docker-compose logs -f multi-document-upload-service
   

2. Check if job completed successfully:

   curl http://localhost:8000/api/multi-docs/jobs/{job_id}
   

3. Check Neo4j connection:

   docker-compose logs neo4j | grep -i error
   

4. Verify Neo4j is running:

   docker-compose ps neo4j
   

5. Test Neo4j connection manually:

   docker-compose exec neo4j cypher-shell -u neo4j -p password "MATCH (n) RETURN count(n)"
   

Next Steps

1. Run the diagnostic queries above
2. Check the service logs for errors
3. Verify the job status via API
4. Re-upload documents after fixing dependencies
5. Check if relations were actually extracted (job status should show relation count)