apoc.cypher.runTimeboxed

This procedure is not considered safe to run from multiple threads. It is therefore not supported by the parallel runtime. For more information, see the Cypher Manual → Parallel runtime.

Details
Syntax	`apoc.cypher.runTimeboxed(statement, params, timeout, config) :: (value)`
Description	Terminates a Cypher statement if it has not finished before the set timeout (ms).
Input arguments	Name	Type	Description
	`statement`	`STRING`	The Cypher statement to run.
	`params`	`MAP`	The parameters for the given Cypher statement.
	`timeout`	`INTEGER`	The maximum time the statement can run for.
	`config`	`MAP`	`{ failOnError = false :: BOOLEAN, appendStatusRow = false :: BOOLEAN }`. The default is: `{}`. Introduced in APOC 2025.01
Return arguments	Name	Type	Description
Return arguments	`value`	`MAP`	The result returned from the Cypher statement.

Configuration parameters

This procedure supports the following config parameters:

Config parameters
name	type	default	description
failOnError	BOOLEAN	false	If an error is encountered, or the timeout is reached an error will be thrown.
appendStatusRow	BOOLEAN	false	The last row returned will be a map containing the status of the query: `{ wasSuccessful :: BOOLEAN, wasTerminated :: BOOLEAN, failedWithError :: BOOLEAN, error :: STRING }`.

Setting a global transaction timeout

To add a timeout to the length a query can run in Neo4j, you can set a query timeout using a configuration parameter. This can help prevent long-running queries from impacting the system. You can configure this timeout in the Neo4j configuration file by setting the db.transaction.timeout property to the desired timeout value.

For example, to set a query timeout of 5 seconds, you can add the following line to your Neo4j configuration file:

db.transaction.timeout=5s

You can find more information about configuring query timeouts in the Neo4j documentation here.

Using a Driver

It is possible to set a timeout per transaction when calling Cypher with a Driver.

For example, the Java Driver QueryConfig can be given a Duration timeout by using the withTimeout() method:

// import org.neo4j.driver.QueryConfig;

var result = driver.executableQuery("MATCH (p:Person) RETURN p.name")
.withConfig(QueryConfig.builder().withTimeout(Duration.ofSeconds(3)).withDatabase("neo4j").build())
.execute();

Usage Examples

The examples in this section are based on a sample graph with 10000 nodes, each with 50 relationships with the label "Node" and Type "CONNECTED_TO".

The query below calculates the cross product of shortest paths for every pair of nodes.

MATCH (n:Node), (m:Node)
WHERE n <> m
MATCH path = shortestpath((n)-[:CONNECTED_TO*]-(m))
RETURN n, m, length(path) AS path;

This query returns 999,000 rows, but it takes a while to return all of those rows.

We can use the apoc.cypher.runTimeboxed procedure to return the paths computed within a threshold defined in ms. We can return the results computed within 100ms, by running the query below:

CALL apoc.cypher.runTimeboxed("match (n:Node), (m:Node)
WHERE n <> m
MATCH path = shortestpath((n)-[:CONNECTED_TO*]-(m))
RETURN n, m, length(path) AS path", {}, 100)
YIELD value
RETURN value.n.uuid, value.m.uuid, value.path;

Results
value.n.uuid	value.m.uuid	value.path
"67dd7a13-dc8d-4d82-9ab3-383d66c54fe4"	"62b0578a-cae5-4d45-8a47-5553692a6f22"	1
"67dd7a13-dc8d-4d82-9ab3-383d66c54fe4"	"9d910497-1aca-48e8-a14c-cd04528675ab"	1
"67dd7a13-dc8d-4d82-9ab3-383d66c54fe4"	"dde31015-73a9-4d22-bf57-ee13a8f7eeb0"	1
"67dd7a13-dc8d-4d82-9ab3-383d66c54fe4"	"6040453e-c705-4755-95f3-3b673d10ae54"	1
"67dd7a13-dc8d-4d82-9ab3-383d66c54fe4"	"bb2a9b42-71ab-4219-beae-a1e99353921f"	1
"67dd7a13-dc8d-4d82-9ab3-383d66c54fe4"	"856a4b54-d027-4438-bbee-fd34d9a6990d"	1
"67dd7a13-dc8d-4d82-9ab3-383d66c54fe4"	"d3e325b4-7691-400a-a819-787c065d537c"	1
….
1022 rows available after 9 ms, consumed after another 1 ms

More documentation of apoc.cypher.runTimeboxed