gograph-import

Overview ¶

Command gograph-import builds a GoGraph store from CSV files, offline, at bulk-loader speed.

It is the answer to a gap the round-3 comparative audit measured: loading 200 000 edges through the Cypher write path took 35 m 33 s, against 977 ms for Memgraph and 2.39 s for Neo4j, while the fast ingest path inside the module was reachable from nothing a user could call.

Why a command and not a Cypher clause ¶

The import needs exclusive ownership of the store directory: it publishes a whole snapshot, which under a live server would race the checkpointer and invalidate open readers' view. It is also not a transaction (see the durability contract below), so dressing it as a Cypher statement inside a session would promise semantics it does not have. Neo4j draws the same line — neo4j-admin database import is a separate offline tool from LOAD CSV.

Usage ¶

gograph-import -store DIR -nodes nodes.csv -edges edges.csv [flags]

The store directory must not exist, or must exist and be empty. Importing into a directory that already holds data is refused, not merged.

CSV format ¶

The nodes file has a header row. One column is the node key; every other column becomes a property, except columns named in -node-labels, whose values become labels. The edges file likewise has a header row with a source column, a target column, an optional type column and an optional weight column; every other column becomes an edge property.

nodes.csv:  id,name,age
            n1,Alice,30

edges.csv:  src,dst,type,since
            n1,n2,KNOWS,2020

Property values are typed by inspection: an integer parses as an integer, a decimal as a float, true/false as a boolean, anything else as a string. Pass -string-props to disable inference and store every property as a string, which is the safe choice when a column holds identifiers that merely look numeric.

Durability contract ¶

The whole import is atomic and nothing else about it is. The snapshot is assembled under <store>/snapshot.tmp and renamed into place, and a rename within a directory is atomic, so the store either has no snapshot or a complete one — no reader can ever observe a partial import. A crash before the rename leaves the store exactly as it was; the partial assembly is invisible to recovery and removed by it.

What this is NOT: a transaction. There is no transaction id, no write-ahead log record, no isolation level and no rollback once published — undoing an import means deleting the directory. There is no per-record durability acknowledgement and no resumption point, so a crash partway through means re-running the whole import. And it is concurrent with nothing: no reader, writer or checkpointer may touch the directory while it runs.