ALTER SYSTEM

Available since: v3.0.0

The ALTER SYSTEM statement is used to alter the entire datastore. It can be used to compact the system, to set or drop a systemwide query timeout, or to set the compatibility level of new databases.

This statement is the only ALTER statement that does not have a corresponding DEFINE statement.

Statement syntax

ALTER SYSTEM 
    COMPACT |
    QUERY_TIMEOUT @duration |
    DROP QUERY_TIMEOUT |
    COMPATIBILITY 3 | 4

QUERY_TIMEOUT clause

A query timeout can be set for the system as a whole. The minimum possible timeout is one millisecond, below which the value will be set as NONE.

ALTER SYSTEM QUERY_TIMEOUT 100ns;
INFO FOR ROOT.config;

{ QUERY_TIMEOUT: NONE }

Any value above 1ms will set the timeout, beyond which no query that takes any longer than this will succeed.

ALTER SYSTEM QUERY_TIMEOUT 1ms;
FOR $_ IN 0..1000 {
    FOR $_ IN 0..1000 {
        CREATE |person:1000|;
    }
};

'The query was not executed because it exceeded the timeout: 1ms'

COMPATIBILITY clause

Available since: v4.0.0

Sets the compatibility level that a database starts at when a DEFINE DATABASE statement does not give one. A datastore created by SurrealDB 4.0 starts new databases at level 4. One that a 3.x release created starts them at level 3, so that every database in it behaves the same way until the level is raised.

ALTER SYSTEM COMPATIBILITY 4;

The clause changes only databases defined afterwards. To change an existing database, use ALTER DATABASE.

COMPACT clause

Compacts the entire datastore. To compact other resources, use ALTER NAMESPACE to compact the current namespace keyspace, ALTER DATABASE to compact the current database keyspace, or ALTER TABLE to compact a specific table keyspace.

The storage engine carries out the compaction. In SurrealDB 4.0, SurrealKV supports it: it writes recent changes to disk, merges the data files that hold the keys, and drops deleted data and old versions that no reader can see, which frees their space. The statement returns once the compaction is done, and reads and writes carry on meanwhile. Before 4.0, RocksDB was the only engine that supported compaction requests. The in-memory engine and TiKV do not support them, and return the following error:

'There was a problem with the key-value store: The storage layer does not support compaction requests.'

A successful compaction returns NONE.

ALTER SYSTEM COMPACT;

NONE