relate push

relate push copies a subgraph of a local storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary into a Neo4j or Aura database over the HTTP Query API v2, then exits. It is the mirror of relate pull: the same credentials file, the same URI rules, the same transport. Push merges each node and relationship on a key taken from the store's constraints, sends batched, parameterized statements, never deletes anything on the remote, and prints a report of what it created, updated, and skipped.

--dry-run prints the plan without contacting the remote. No Neo4j server was available when this page was verified: the dry runs and refusals shown are recorded runs of the relate binary, and what a push does against a live remote is described from relate's CLI specification and its agent skill, not from a run.

Synopsis

relate push --to CREDS --database PATH [--query Q | --labels L1,L2 | --types T1,T2] [--batch-size N] [--nodes-update POLICY] [--rels-update POLICY] [--updated-at NAME[,NAME]] [--rel-mode MODE] [--merge-key LABEL:PROP[,PROP]] [--rel-key TYPE:PROP[,PROP]] [--unkeyed-labels ACTION] [--dry-run] [--json] [--allow-plaintext]

Pushpush relate push: the command that copies a scoped subgraph of a store into Neo4j or Aura over the HTTP Query API; the mirror of relate pull. Read more in the glossary is a command, so it takes only its own flags. --namespace is refused in both positions, because push always reads the neo4j namespace.

Options

A flag that takes one value may appear once: a second --to, --query or --rel-mode is a usage error. --dry-run, --json and --allow-plaintext may also appear once. --merge-key and --rel-key repeat once per label or type, --updated-at repeats but never names a property twice, and --labels and --types add to their lists when repeated.

The remote and its credentials

--to takes a credentials file in the format relate pull --from reads (NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, optional NEO4J_DATABASE), or a Query API URI. With a URI, the username, password and database come from the process environment; a missing one is an error such as NEO4J_USERNAME missing from push --to.

Everything else about the connection is pull's: the URI scheme mapping, the refusal of a URI that carries a password, the warning for a credentials file other users can read, and the refusal of plain http:// to a non-loopback host unless --allow-plaintext is given. The pull reference has the tables.

The source store

Scope

Two selectors together are a usage error: push takes one of --query, --labels, or --types (none pushes the whole store).

Merge keys

Push writes a node with MERGE on its label's merge key, so pushing twice does not duplicate it. The key comes from the store's uniqueness, node key and relationship key constraintsconstraint A rule the store enforces on every write, such as a unique property, a required property, a property type or a node key; a violating write fails. Read more in the glossary, composite keys included. --merge-key LABEL:PROP[,PROP] sets or overrides one label's key, once per label.

Relationships follow --rel-mode:

Update policies

--nodes-update and --rels-update decide what happens to an entity that already exists on the remote. Each takes a global policy (add), a per-entity list (Person=replace,Project=skip), or both, where a bare policy in the list is the default for every entity it does not name.

--updated-at NAME[,NAME] names timestamp properties to compare, the first one present on each side winning. When both the local entity and the remote row carry one, a strictly newer remote row is skipped and counted as remote-newer, and an equal or newer local row is written. Temporal values and numbers compare; any other pair is incomparable, is written under the policy, and adds to the warn count.

The report

Push prints one row per entity, then a summary line. The skipped column adds up the four reasons: unkeyed, policy, remote-newer and dangling. warn counts the --updated-at pairs that could not be compared. A dry run also prints each entity's statement shape and ends with dry run: <n> entities, <m> rows planned; nothing was sent.

--json prints the same report as one JSON object:

In a dry run nothing is read from the remote, so created counts every row in scope.

Against a live remote

From the CLI specification, not from a run:

• Before it writes an entity, push reads the remote's current rows for that entity by the same merge key, so the report can separate created from updated and --updated-at can compare timestamps.
• Every value is sent as a typed parameter, so DATE, POINT, UUID and vector properties keep their Cypher type on the remote. A byte-array property fails the push: push failed: property "<key>": a byte array property ….
• Rows go in batches of --batch-size (default 5000) per statement.
• Nothing is deleted on the remote.
• Pushing the same scope twice, under add or skip, with keyed or structural relationships, leaves the remote as one push did.
• A failing batch stops the push, names the entity, the batch and the row range, prints the partial report of what landed, and exits 1.
• The report does not compare the remote's constraints with the local ones: a local merge key that the remote does not enforce still merges, but the remote may already hold duplicates of it.

A failure before any write is a recorded run. With a uniqueness constraint on Person only, --labels Person, and NEO4J_URI=http://127.0.0.1:8873 in local.env, where nothing was listening, the pre-read fails, the report prints with nothing written, and the push exits 1. The timing and the text after io: vary by run and by operating system (this recording is from macOS):

relate push --to local.env --database ./team.rl --labels Person

entity                       total  created  updated  skipped  warn  merge key  policy  batches
Person                           3        0        0        0     0  name       add           0
(Person)-[:KNOWS]->(Person)      1        0        0        0     0             add           0
(dangling)                       4        0        0        4     0             skip          0
pushed 0 rows in 0 statements (0 bytes) in 1 ms
Error: push failed: pre-read of Person failed: HTTP request to http://127.0.0.1:8873/db/neo4j/query/v2 failed: io: Connection refused (os error 61)

Errors and exit codes

The usage messages, each on stderr after Error: :

Examples

The setup writes the team graph (five nodes, five relationships) into ./team.rl and a credentials file that names a documentation host, neo4j.example.com; a dry run never contacts it.

printf 'NEO4J_URI=https://neo4j.example.com:7473\nNEO4J_USERNAME=neo4j\nNEO4J_PASSWORD=<password>\n' > neo4j.env
chmod 600 neo4j.env
relate --database ./team.rl "CREATE (ada:Person {name: 'Ada', role: 'engineer'}),
       (grace:Person {name: 'Grace', role: 'engineer'}),
       (noor:Person {name: 'Noor', role: 'maintainer'}),
       (relate:Project {name: 'relate', language: 'Rust'}),
       (tck:Project {name: 'opencypher-tck', language: 'Gherkin'}),
       (ada)-[:WORKS_ON {since: 2024}]->(relate),
       (grace)-[:WORKS_ON {since: 2023}]->(relate),
       (grace)-[:WORKS_ON {since: 2022}]->(tck),
       (noor)-[:MAINTAINS]->(relate),
       (ada)-[:KNOWS]->(grace)" > /dev/null

The store has no constraints yet, so no label has a merge key and the plan skips everything:

relate push --to neo4j.env --database ./team.rl --dry-run

entity                                      total  created  updated  skipped  warn  merge key  policy  batches
Person (unkeyed)                                3        0        0        3     0             add           0
Project (unkeyed)                               2        0        0        2     0             add           0
(Person)-[:KNOWS]->(Person) (unkeyed)           1        0        0        1     0             add           0
(Person)-[:MAINTAINS]->(Project) (unkeyed)      1        0        0        1     0             add           0
(Person)-[:WORKS_ON]->(Project) (unkeyed)       3        0        0        3     0             add           0
dry run: 5 entities, 10 rows planned; nothing was sent

The next two statements write a uniqueness constraint on each label into ./team.rl, which gives both labels a key. The second dry run plans every row and prints the statements:

relate --database ./team.rl "CREATE CONSTRAINT person_name IF NOT EXISTS FOR (p:Person) REQUIRE p.name IS UNIQUE" > /dev/null
relate --database ./team.rl "CREATE CONSTRAINT project_name IF NOT EXISTS FOR (p:Project) REQUIRE p.name IS UNIQUE" > /dev/null
relate push --to neo4j.env --database ./team.rl --dry-run

entity                            total  created  updated  skipped  warn  merge key  policy  batches
Person                                3        3        0        0     0  name       add           1
Project                               2        2        0        0     0  name       add           1
(Person)-[:KNOWS]->(Person)           1        1        0        0     0             add           1
(Person)-[:MAINTAINS]->(Project)      1        1        0        0     0             add           1
(Person)-[:WORKS_ON]->(Project)       3        3        0        0     0             add           1
Person: UNWIND $rows AS row MERGE (n:`Person` {`name`: row.key.`name`}) SET n += row.props
Project: UNWIND $rows AS row MERGE (n:`Project` {`name`: row.key.`name`}) SET n += row.props
(Person)-[:KNOWS]->(Person): UNWIND $rows AS row MATCH (a:`Person` {`name`: row.start.`name`}) MATCH (b:`Person` {`name`: row.end.`name`}) MERGE (a)-[r:`KNOWS`]->(b) SET r += row.props
(Person)-[:MAINTAINS]->(Project): UNWIND $rows AS row MATCH (a:`Person` {`name`: row.start.`name`}) MATCH (b:`Project` {`name`: row.end.`name`}) MERGE (a)-[r:`MAINTAINS`]->(b) SET r += row.props
(Person)-[:WORKS_ON]->(Project): UNWIND $rows AS row MATCH (a:`Person` {`name`: row.start.`name`}) MATCH (b:`Project` {`name`: row.end.`name`}) MERGE (a)-[r:`WORKS_ON`]->(b) SET r += row.props
dry run: 5 entities, 10 rows planned; nothing was sent

--labels Person keeps the people and the one relationship between two people; the four relationships that reach a project are counted as dangling:

relate push --to neo4j.env --database ./team.rl --dry-run --labels Person

entity                       total  created  updated  skipped  warn  merge key  policy  batches
Person                           3        3        0        0     0  name       add           1
(Person)-[:KNOWS]->(Person)      1        1        0        0     0             add           1
(dangling)                       4        0        0        4     0             skip          0
Person: UNWIND $rows AS row MERGE (n:`Person` {`name`: row.key.`name`}) SET n += row.props
(Person)-[:KNOWS]->(Person): UNWIND $rows AS row MATCH (a:`Person` {`name`: row.start.`name`}) MATCH (b:`Person` {`name`: row.end.`name`}) MERGE (a)-[r:`KNOWS`]->(b) SET r += row.props
dry run: 3 entities, 8 rows planned; nothing was sent

Two selectors are a usage error:

relate push --to neo4j.env --database ./team.rl --labels Person --types KNOWS
echo "exit=$?"

Error: push takes one of --query, --labels, or --types (none pushes the whole store)
Usage: relate push --to CREDS --database PATH [--query Q | --labels L1,L2 | --types T1,T2] [--batch-size N] [--nodes-update POLICY] [--rels-update POLICY] [--updated-at NAME[,NAME]] [--rel-mode MODE] [--merge-key LABEL:PROP[,PROP]] [--rel-key TYPE:PROP[,PROP]] [--unkeyed-labels ACTION] [--dry-run] [--json] [--allow-plaintext]
Run 'relate push --help' for more information.
exit=2

See also

• relate pull: the mirror command, and the credential and URI tables push shares
• Push a subgraph to Neo4j: the task, from a dry run to a verified push
• Schema clauses: the constraints push takes its merge keys from
• Exit codes and errors: the exit codes every command shares
• Problems relate solves: Neo4j subgraph mirror