Dot commands

A dot command is a line that starts with . and that the relate CLI handles itself instead of running as Cypher. There are eight: .help, .quit (also .exit), .begin, .commit, .rollback, .checkpoint, .info and .timer. They work the same in the interactive shell and in a script piped to relate query. A dot command ends at the end of its line and needs no ;. Any other word starting with . fails with Error: unknown command <name>.

Synopsis

cypher> .<command> [argument]
printf '.<command>\n' | relate query [--database PATH]

Every command

.help

.help prints the summary of what the session accepts:

printf '.help\n' | relate query

  Cypher statement ending with ;
  .begin / .commit / .rollback / .checkpoint
  .info
  .timer on|off
  .quit

.quit and .exit

.quit and .exit end the session with exit code 0. In a script, the lines after it are never read:

printf ".quit\nCREATE (:Note {text: 'never runs'});\n" | relate query --mode envelope
echo "exit=$?"

exit=0

On a persistent storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary opened for writing, the session takes a final checkpoint before it exits. If that fails, it prints Error: final checkpoint failed: <reason> and exits 1. End of input, or Ctrl-D on an empty line in the interactive shell, ends the session the same way.

A session that ends with a transaction open discards that transaction's writes and prints a warning on stderr. The exit code depends on the session:

printf '.begin\nCREATE (:Note);\n.quit\n' | relate query
echo "exit=$?"

{"planCache":"miss","timings":{"elapsed_ms":0.49208300000000005,"execute_ms":0.366208,"lex_parse_ms":0.001916,"lower_ms":0.003416,"parse_ms":0.11995800000000001,"plan_ms":0.001583,"result_generation_ms":0.000292,"rewrite_ms":0.000292}}
Warning: exiting with an open transaction; rolling back uncommitted changes. Use .commit before exiting to persist them.
exit=1

.begin, .commit, and .rollback

Without .begin, each statement that writes commits on its own when it succeeds. .begin opens an explicit transactiontransaction A unit of work that commits as a whole or not at all; each statement is its own transaction unless an explicit begin … commit groups several. Read more in the glossary: the statements after it see its writes, and nothing is committed until .commit. .rollback discards everything since .begin. All three print nothing on success. This example writes two Note nodes to a new directory store, ./notes; later examples on this page read it --read-only.

printf ".begin\nCREATE (:Note {text: 'kept'});\nCREATE (:Note {text: 'also kept'});\n.commit\n" | relate query --database ./notes
relate --database ./notes --read-only --mode jsonl "MATCH (n:Note) RETURN count(n) AS notes"

{"planCache":"miss","timings":{"elapsed_ms":0.4615,"execute_ms":0.300375,"lex_parse_ms":0.003375,"lower_ms":0.003375,"parse_ms":0.153792,"plan_ms":0.0018750000000000001,"result_generation_ms":0.000041,"rewrite_ms":0.0015}}
{"planCache":"miss","timings":{"elapsed_ms":0.025541,"execute_ms":0.00575,"lex_parse_ms":0.001458,"lower_ms":0.001459,"parse_ms":0.018542,"plan_ms":0.000833,"result_generation_ms":0.000042,"rewrite_ms":0.000125}}
{"notes":2}
{"planCache":"miss","timings":{"elapsed_ms":0.5155,"execute_ms":0.351375,"lex_parse_ms":0.030040999999999998,"lower_ms":0.041875,"parse_ms":0.105459,"plan_ms":0.050959,"result_generation_ms":0.00025,"rewrite_ms":0.007833}}

Transactions do not nest, and .commit or .rollback needs an open one:

printf '.commit\n' | relate query
echo "exit=$?"

semantic error: no transaction
exit=1

In the interactive shell a failed statement does not end the session. It rolls back its own partial writes and leaves the transaction failed: every later statement and .commit print semantic error: transaction failed; rollback required until .rollback. The transactions concept page explains what a transaction sees and when it commits.

.checkpoint

.checkpoint writes a checkpointcheckpoint The step that writes a fresh snapshot of committed state and recycles old WAL segments: every 300 seconds by default, on clean exit, and on .checkpoint. Read more in the glossary now: the snapshot is rewritten to the current state and the WAL segments it covers are recycled. It prints nothing. On :memory: it succeeds without writing anything. A store opened --read-only refuses it with exit code 1:

printf '.checkpoint\n' | relate query --database ./notes --read-only
echo "exit=$?"

semantic error: WriteOnReadOnlyAccessDatabase: No write operations are allowed on this database. The database is in read-only mode on this Neo4j instance.
exit=1

A persistent store also checkpoints on a timer (--checkpoint-interval-secs, default 300) and when a session ends. The WAL and checkpoints page covers what a checkpoint writes.

.info

.info prints a read-only report on the open store, in three parts:

On :memory: with --mode csv, each catalog result is its header line:

printf '.info\n' | relate query --mode csv

store:                        :memory: (store metadata not applicable)
nodes:                        0
relationships:                0
indexes:
id,name,state,populationPercent,type,entityType,labelsOrTypes,properties,indexProvider,owningConstraint,lastRead,readCount
constraints:
id,name,type,entityType,labelsOrTypes,properties,ownedIndex,propertyType,enforcedLabel

On a directory store, the metadata lines come first. Sizes and timestamps differ from store to store, so this example keeps five lines:

printf '.info\n' | relate query --database ./notes --read-only --mode csv | grep -E '^(layout|codec|checkpoint LSN|nodes|relationships):'

layout:                       native directory
codec:                        parquet
checkpoint LSN:               1
nodes:                        2
relationships:                0

A store that has never been checkpointed reports a snapshot: line reading none yet (no checkpoint since creation) in place of the codec and checkpoint fields. A json codec store reports unavailable as its format version, with a note: line saying the format version lives in its graph.json; its live counts and catalog print as usual.

.timer

.timer on turns on per-statement timing, and .timer off turns it off; it is off when a session starts. Each prints its new state. While it is on, every statement that succeeds prints one line on stdout after its result: Time: <total>ms (parse <ms> / plan <ms> / execute <ms>). The times change from run to run. Any argument other than on or off, in lowercase, prints the usage line and leaves the state unchanged:

printf '.timer on\n.timer off\n.timer ON\n' | relate query
echo "exit=$?"

Timer: on
Timer: off
Usage: .timer on|off
exit=0

Commands that do not exist

Many shells have more dot commands. relate has only the eight on this page, and every other word fails with Error: unknown command <name>, exit code 1 in a script. The jobs those commands do elsewhere are done this way:

printf '.mode csv\n' | relate query
echo "exit=$?"

Error: unknown command .mode
exit=1

See also

• Use the interactive shell: multi-line statements, history, and leaving the shell
• Script the CLI: .begin and .commit around a migration script
• relate CLI: the invocation forms and the dot commands in brief
• Transactions and concurrency: what an explicit transaction sees