WAIT options

Aside from SHOW DATABASES, all database management commands accept an optional WAIT/NOWAIT sub-clause. The WAIT/NOWAIT sub-clause allows you to specify a time limit in which the command must complete and return.

The options are:

  • WAIT n SECONDS - Returns once completed or when the specified time limit of n seconds is up.

  • WAIT - Returns once completed or when the default time limit of 300 seconds is up.

  • NOWAIT - Returns immediately.

A command using a WAIT sub-clause automatically commits the current transaction when it executes successfully, as the command needs to run immediately for it to be possible to WAIT for it to complete. Any subsequent commands executed are therefore performed in a new transaction. This is different from the usual transactional behavior, and for this reason, it is recommended that these commands be run in their own transaction. The default behavior is NOWAIT, so if no clause is specified the transaction behaves normally and the action is performed in the background post-commit.

The WAIT sub-clause was added as an option to the ALTER DATABASE command in Neo4j 5.7.

A command with a WAIT clause may be interrupted whilst it is waiting to complete. In this event, the command will continue to execute in the background and will not be aborted.
Example 1. Create a database with WAIT
Query
CREATE DATABASE slow WAIT 5 SECONDS
Result
+-------------------------------------------------------+
| address          | state      | message     | success |
+-------------------------------------------------------+
| "localhost:7687" | "CaughtUp" | "caught up" | TRUE    |
+-------------------------------------------------------+

The success column provides an aggregate status of whether or not the command is considered successful and thus every row will have the same value. This column is to determine, for example in a script, whether or not the command has been completed successfully without timing out.