Skip to content

Import and export

Import

From the console

Open a database, then Import (owners, admins and developers):

  1. Pick a file: CSV or TSV with a header row, a JSON array of objects, or JSON Lines. The file is read in your browser.
  2. Map it to nodes of one label (choose the property types, an optional key to MERGE on, and optionally a uniqueness constraint on that key), or to relationships between existing nodes found by key.
  3. Preview the first rows, then Import.

Rows are loaded in batches; each batch is one write request. The importer waits out rate limits, splits batches that are too large, and isolates a row that fails so the rest still load; failed rows are listed with their record number at the end. You can pause, resume or stop a run: MERGE batches are safe to repeat.

PlanLargest fileMost records per file
Free10 MB100,000
Pro100 MB1,000,000
Scale250 MB2,500,000

Every import is recorded in the audit log with its counts. An empty database also offers Load sample dataset (a movies graph of 18 movies, 47 people and 81 relationships) from the Query tab.

From code

The SDKs batch rows for you (1,000 rows or 1 MiB per batch by default), wait out rate limits and cold starts, and split a batch that is too large.

import { NamiDB } from '@namidb/cloud';
const db = new NamiDB();
await db.query('movies', 'CREATE CONSTRAINT IF NOT EXISTS FOR (p:Person) REQUIRE p.id IS UNIQUE');
await db.importNodes('movies', people, { label: 'Person', key: 'id' });
await db.importRelationships('movies', follows, {
type: 'FOLLOWS',
from: { label: 'Person', key: 'id' },
to: { label: 'Person', key: 'id' },
});
// Any statement that reads $rows:
await db.bulkWrite('movies', 'UNWIND $rows AS row MERGE (m:Movie {title: row.title})', titles, { idempotent: true });

Tips:

  • Create a uniqueness constraint on the key first, so each MERGE is a point lookup instead of a scan.
  • Import nodes before the relationships that connect them.
  • Large one-off loads use many write requests: a 10 million row import at 1,000 rows per batch is 10,000 write requests.

Export

An export is a portable copy of one database, written as files you download. It is a point-in-time snapshot: it holds the database exactly as it was when the export started. Writes made while it runs are not included, so totals and relationships always match.

From the console: database page → Export (owners and admins; confirm with your second factor if you use one). With the API: POST /databases/{database}/exports (write scope), then poll GET /exports/{id}. With the CLI: namidb exports create movies --wait, then namidb exports download <id> import.cypher.

You are emailed when it is ready, and the export.ready alert reaches your webhooks and the recipients chosen on the Alerts page. Each export holds:

FileContents
nodes.jsonlOne node per line: id, labels, properties
relationships.jsonlOne relationship per line: type, start and end node ids, properties
import.cypherOne statement per line that recreates the schema (constraints and range, full-text and vector indexes), nodes and relationships in NamiDB or Neo4j
manifest.jsonCounts, the snapshot time (snapshot.taken_at), and each file’s size and SHA-256
  • Files can be downloaded for 7 days, then they are deleted (410 export_expired afterwards). Every download is in the audit log.
  • One export per database at a time (409 export_in_progress), and 20 per organization per 24 hours.
  • Exports are not billed as requests. Their files count as storage while they exist, and while an export runs it works from a temporary copy of the database, which counts as storage until the export finishes.
  • Nodes with very many relationships are exported in full.
  • Full-text and vector indexes (dimension and similarity function included) are recreated by import.cypher. A vector index that uses NamiDB-specific build options is written in NamiDB’s syntax after a // NamiDB only comment; skip that statement when loading into Neo4j.

Loading an export

import.cypher is meant for an empty database. It holds one statement per line, each ending in ; and small enough for one request, plus // comment lines. Run the statements in order:

Terminal window
# With the CLI's shell (stops at the first error):
namidb shell movies-copy < import.cypher
# Or with curl, one statement per request:
grep -v '^//' import.cypher | while IFS= read -r stmt; do
jq -n --arg q "${stmt%;}" '{query: $q}' |
curl -sf https://db.namidb.com/v1/movies-copy/cypher \
-H "Authorization: Bearer $NAMIDB_API_KEY" -H "Content-Type: application/json" -d @- > /dev/null ||
{ echo "failed: ${stmt:0:80}"; break; }
done

Nodes get a temporary label and property while loading so relationships can find their ends; the last statement removes them. The same file loads into a self-hosted server or into Neo4j (cypher-shell -f import.cypher; on Neo4j, also drop the temporary constraint named in the file’s last comment).

Exports when you can’t query

Your data stays exportable even when queries are refused:

  • a suspended organization can still export from the console;
  • a deleted organization can be exported during its 30-day recovery period from your account page (Exports).