How to Export to Neo4j

The extension exports the traceability graph to files Neo4j can import — CSV (nodes + relationships) and Cypher (an executable script). The export is file-based only: there is no direct Neo4j connection; you import the generated files into Neo4j yourself (for example with LOAD CSV, cypher-shell, or the Neo4j Data Importer).

Export from the CLI

# Export a local directory as CSV
npx antora-tracer export neo4j -i modules/ROOT/pages/ --format csv -o ./neo4j-export/

# Export the complete graph from an Antora playbook as Cypher
npx antora-tracer export neo4j antora-playbook.yml --format cypher -o ./neo4j-export/

The -i flag processes a local directory first (parsing items and relationships), then exports the graph. Pass a playbook path instead to harvest every component and repository in that playbook and export the complete graph. Use --config or --preset to specify your configuration.

CSV format

Two files are produced:

  • nodes.csv — items with authored id, canonical identity, component, version, role, title, and attributes.

  • relationships.csv — edges with canonical source and target identities, authored sourceId and targetId, and type.

For playbook exports, identity combines the component, version, and authored item ID with NUL separators. Unscoped local exports keep the authored ID as identity. Relationship source and target reference these canonical node identities. sourceId and targetId keep the authored IDs.

Import into Neo4j using identity as the node key:

LOAD CSV WITH HEADERS FROM 'file:///nodes.csv' AS row
CREATE (n:Item {id: row.id, identity: row.identity, component: row.component, version: row.version, role: row.role, title: row.title});

LOAD CSV WITH HEADERS FROM 'file:///relationships.csv' AS row
MATCH (a:Item {identity: row.source}), (b:Item {identity: row.target})
CREATE (a)-[r:RELATES {type: row.type, sourceId: row.sourceId, targetId: row.targetId}]->(b);

Create indexes for faster queries:

CREATE INDEX item_identity FOR (n:Item) ON (n.identity);
CREATE INDEX item_role FOR (n:Item) ON (n.role);

Cypher format

A single import.cypher file with CREATE statements for all nodes and relationships. Execute directly in Neo4j Browser or via cypher-shell:

cat import.cypher | cypher-shell -u neo4j -p password

Example queries

Once imported, query the graph:

// Requirements without any implementation or test coverage
MATCH (r:Item {role: 'requirement'})
WHERE NOT EXISTS {
  MATCH (r)<-[:RELATES]-(:Item)
}
RETURN r.id, r.title ORDER BY r.id

// Full traceability chain: requirement → design → implementation → test
MATCH path = (r:Item {role: 'requirement'})<-[:RELATES]-(d:Item {role: 'design'})
           -[:RELATES]->(i:Item {role: 'implementation'})<-[:RELATES]-(t:Item {role: 'test'})
RETURN r.id, d.id, i.id, t.id

// Impact analysis: what depends on REQ-001?
MATCH (r:Item {id: 'REQ-001'})
OPTIONAL MATCH (r)<-[:RELATES]-(d:Item {role: 'design'})
OPTIONAL MATCH (d)-[:RELATES]->(i:Item {role: 'implementation'})
RETURN r.id, collect(d.id) as designs, collect(i.id) as implementations

Related