Sleep function
This function can be used to introduce a delay or pause in the execution of a query or a batch of queries for a specific amount of time.
| Function | Description |
|---|
sleep() | Delays or pauses in the execution of a query or a batch of queries. |
sleep
The sleep function delays or pauses the execution of a query or a set of statements.
API DEFINITION
sleep(duration) -> none
The following example shows this function, and its output, when used in a RETURN statement:
RETURN sleep(1s);
RETURN sleep(500ms);
SurrealDB also has a SLEEP statement statement that accepts a datetime; however, the sleep function can be used in more dynamic ways such as the following example that simulates a 100ms delay between each record in a query.
CREATE |person:3|;
LET $now = time::now();
SELECT *,
sleep(100ms) AS _,
time::now() - $now AS elapsed
FROM person;
Response
[
{
_: NONE,
elapsed: 101ms457µs,
id: person:fkgvriz1kl2tcgv6yqfq
},
{
_: NONE,
elapsed: 203ms599µs,
id: person:lgibwdgtvx4v8ck60guk
},
{
_: NONE,
elapsed: 305ms728µs,
id: person:pr0uby896y1az2p44wtw
}
]
SLEEP during parallel operations
The sleep() function does not interfere with operations that are underway in the background, such as a DEFINE INDEX statement using the CONCURRENTLY clause.
CREATE |user:50000| SET name = id.id() RETURN NONE;
DEFINE INDEX unique_name ON TABLE user FIELDS name UNIQUE CONCURRENTLY;
INFO FOR INDEX unique_name ON TABLE user;√
RETURN sleep(50ms);
INFO FOR INDEX unique_name ON TABLE user;
RETURN sleep(50ms);
INFO FOR INDEX unique_name ON TABLE user;
RETURN sleep(50ms);
INFO FOR INDEX unique_name ON TABLE user;
Possible output
{
building: {
initial: 0,
pending: 0,
status: 'indexing',
updated: 0
}
}
{
building: {
initial: 100,
pending: 20,
status: 'indexing',
updated: 0
}
}
{
building: {
initial: 100,
pending: 4,
status: 'indexing',
updated: 16
}
}
{
building: {
status: 'ready'
}
}
Use cases
Putting a database to sleep can be useful in a small number of situations, such as:
- Testing and debugging: can be used to understand how concurrent transactions interact, test how systems handle timeouts and delays, simulate behaviour in more distant regions with longer latency
- Throttling: can be used to throttle the execution of operations to prevent the database from being overwhelmed by too many requests at once
- Security measures: can be used to slow down the response rate of login attempts to mitigate the risk of brute force attacks
