# Native Neo4j dump imports

[Wiki](../README.md) / [Clients and drivers](README.md)

Galactus reads offline Neo4j **4.x and 5.x** `.dump` files directly in Rust.
No Java, Neo4j installation, Docker container or conversion service is needed.
The database image includes the native reader.

Use a dump created after a **clean Neo4j shutdown**. This reader imports the
stored graph; it does not replay transaction logs or recover a crashed store.
For a store needing recovery, recover it in the original Neo4j version and
create a fresh offline dump first.

Use `2026.09.23-neo4j-streaming` or a newer release for both the database and
Explorer. Both Docker Hub images support Linux AMD64 and ARM64. Pull and
recreate both services to enable streaming uploads. The original
`2026.09.23-neo4j-import` images predate streaming and retain the 63 MiB
Explorer upload limit.

## Import

Choose an empty target database in Explorer, click **Import**, and select `.dump`.
Explorer shows the target and import behavior before uploading. Its file picker
accepts explicit `.gdb` and `.dump` extensions. **Script** separately accepts
Cypher text in `.cypher`, `.cql` and `.txt` files. `.gdb` snapshots retain their
existing replace-and-restore behavior and licensing requirements.

From Cypher, supply a path on the **database server's** filesystem:

```cypher
CALL gdb.neo4j.import('/data/northwind-50.dump')
YIELD format, nodes, relationships, properties, schemaImported, done
RETURN format, nodes, relationships, properties, schemaImported, done;
```

Or pass the file contents as a Bolt byte-array parameter:

```cypher
CALL gdb.neo4j.import($dump)
```

Imports require write privileges and an empty graph. Existing data is never
deleted. The whole graph is decoded and validated before writes begin, and all
writes form one atomic statement: an invalid value, target constraint failure,
or subsequent query error rolls back the import. Explicit transactions may also
roll back a successful import. Normal durable commit semantics apply.

Nodes, labels, properties, directed relationships, parallel edges and self-loops
are preserved. Internal Neo4j node IDs are remapped; property values named `id`
are ordinary data and remain unchanged. Neo4j schema, constraints, indexes,
users, authentication settings, transaction history and GDS projections are not
imported (`schemaImported` is always `false`). Recreate the required Galactus
indexes and constraints separately.

## Compatibility and limits

| Component | Supported |
|---|---|
| Archive | Legacy gzip/Zstandard; `DGV1` gzip and `DZV1` Zstandard |
| Neo4j 4 standard stores | `SF4.0.0`, `SF4.3.0` |
| Neo4j 4 aligned stores | `AF4.1.a`, `AF4.3.0` |
| Neo4j 5 record stores | `standard` / `aligned`, store version `1.1` (including tested 5.26 dumps) |
| Values | Booleans, signed integers, floating point, characters/strings, bytes, primitive/string arrays |
| Temporal | Date, local time, local datetime, offset time, offset datetime, duration |
| Spatial | 2D/3D WGS84 and Cartesian points |

Neo4j **3.x**, block stores, high-limit stores, unknown store versions,
named-zone datetime encodings, and temporal/point arrays are rejected with an
error before data is written. Use a logical export for these encodings. A
`.dump` extension alone does not imply that its store format is supported.

Explorer streams `.dump` uploads up to **512 MiB**, including 400 MiB files,
through an authenticated connection using acknowledged **1 MiB** chunks. The
database spools the compressed file to its writable data volume; neither the
Explorer process nor an individual Bolt message buffers the complete upload.
The upload progress display changes to validation/import after the browser has
sent the file. The final success response means the atomic import completed.

The server permits at most **four concurrent uploads/imports**. Reserve up to
512 MiB of temporary disk space per active upload, plus normal database/WAL
capacity. Incomplete uploads make no graph changes. Failure, abort, connection
close and a **60-second receive idle timeout** remove the temporary file.
Uploading does not hold the target write lock. Once the upload completes, the
normal executor rechecks that the target is empty and applies the import under
its write lock. A failed import rolls back the statement.

Transfers are connection-owned and not resumable. If the connection is lost
after the full file was submitted, the atomic import may still complete; check
the target before retrying. A hard process termination can leave reserved
`.neo4j-upload-*.dump` files in `GDB_DATA`; remove those only while the database
server is stopped. The server-side path procedure remains available.

This streams the **transfer and decompression**, not the entire graph build.
The decoder still bounds expanded archives to **1 GiB**, Zstandard
windows to **64 MiB**, dynamic values to **16 MiB**, token tables to **100,000**
entries / **16 MiB** of names per table, label names to **1 MiB** per node,
the graph to **two million entities**, and decoded logical data to a
**1 GiB accounting budget**. The latter is not a cap on process RSS: store buffers,
decoded graph, database and transaction undo/WAL buffers also occupy memory.
Large imports hold the target's write lock until completion.

Archive paths are never extracted to disk. Compression checksums, tar headers,
record references, property chains, token references and relationship endpoints
are checked. This is not a substitute for Neo4j's full store consistency checker.


## Reverse proxies

For Explorer behind nginx, configure its import route to allow the body size,
avoid request buffering, and wait for the final import result. Keep the existing
upstream address and authentication settings:

```nginx
client_max_body_size 512m;
proxy_request_buffering off;
proxy_http_version 1.1;
proxy_read_timeout 3600s;
proxy_send_timeout 300s;
```

These directives belong in the existing Explorer `location` block. See nginx's
[request buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_request_buffering)
and [body-size limit](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size)
documentation. A proxy's own lower limit can still reject an upload.
