Database Admin

Executes a distributed alignment of the database. It must be executed on the Leader server. The alignment computes a checksum of each file and sends them to the replica nodes. Each replica node will compute the checksum on its own files. The files that are mismatching are requested by the replica to the leader. In the future single pages could be transferred instead of the entire file.

Syntax

The command returns which page have been aligned on each server.

Examples

Change a database setting. You can find the available settings in Settings appendix. The update is persistent.

Syntax

Examples

Executes a backup of the current database. The resulting file is a compressed archive using ZIP as algorithm. The archive contains the database directory without the transaction logs. The backup is executed taking a snapshot of the database at the time the command is executed. Any pending transaction will not be in the backup archive. ArcadeDB allows to execute a non-stop backup of a database while it is used without blocking writes or affecting performance. A close requested while a backup is running waits for the backup to complete, and the database keeps serving in the meantime: the archive is always complete, and the close goes ahead right after.

Syntax

Examples

Executes an integrity check and in case of a repair of the database. This command analyzes the following things:

When a vertex’s edge list is unreadable (for example a lost or corrupted chunk of the adjacency linked list), the FIX mode does not delete anything: every edge record stores its own endpoint identities, so the adjacency list is rebuilt from the surviving edge records. After the rebuild, a full-scope FIX (no TYPE/BUCKET filter) also reclaims the orphaned edge-list segments the old, unreachable chains left on disk.

The other shape is a dangling reference: an adjacency entry that points at a record which no longer exists, typically left behind by a vertex deleted by an old release, before edge removal became strict. There is nothing to rebuild in that case - the record the entry names is gone - so FIX drops the entry instead.

Since v26.9.1, an application that reaches such a record before the repair has run is told so plainly, and always in the same way. Removing an entry from the edge list of a vertex whose own record is missing, adding one to it, and deleting that vertex outright all raise VertexNotFoundException, a RecordNotFoundException (answered as HTTP 404) that names the vertex and points at CHECK DATABASE FIX. Creating an edge whose endpoint is such a record raises it too, naming the endpoint - which is not the vertex the statement named. It is deliberately not a NeedRetryException: the record is gone rather than temporarily unreadable, so a retry can only fail identically, and a job walking possibly-stale references can skip that entry instead of spending its retry budget and rolling back the whole transaction. An unreadable chunk of a vertex that does exist keeps raising the retryable ConcurrentModificationException described above - the two are told apart by which record the failure names.

A DELETE VERTEX refused this way is refused before it touches anything: the vertex’s record is checked first, so the failure does not cost a walk over an adjacency list that is about to be rolled back.

That up-front check reads the vertex’s record, so deleting a vertex needs the readRecord permission on its type as well as deleteRecord (see groups). This is not a new requirement in practice, since every way of obtaining the vertex in order to delete it already reads it, but a group granting deleteRecord alone now fails at the first statement of the delete rather than part of the way through it.

While the check runs, its progress (current step and percentage) is visible live in the console, in Studio, and through the HTTP progress endpoint. Run FIX in a maintenance window: like every repair, it assumes no concurrent writers.

Syntax

The optional clauses must appear in the order shown above.

The command returns the integrity check report in one record with the fields:

Vector indexes

Since v26.10.1 the check reads the pages of every LSM_VECTOR index and reports one that has two records on the same vector id. The index appears under corruptedIndexes, and warnings carries how many records are affected and the first few RIDs, each with the record that took its id.

Such an index never keeps its persisted graph. A graph build counts both records, while every load of the same pages keeps only the one written last, so the graph holds more nodes than the load has live vectors and is rejected as stale on the next load. Each search that finds it rejected waits for a full rebuild of the graph, and the rebuild produces the same graph again. The record that lost its vector id is not returned by a vector search until its vector is indexed again. A graph build now logs those records by RID and keeps one record per id, which ends the loop but does not restore them.

While an index has records left out this way it does not compact, because a compaction would erase the shared ids from the pages. The index keeps growing until it is rebuilt. getStats() exposes compactionBlockedBySharedIds and recordsLeftOutBySharedIds so this can be monitored. The check reads every page of each vector index and holds that index’s read lock while it does, so writes to the index wait for the scan.

CHECK DATABASE alone only reports. FIX rebuilds the index from the records, which gives every record that holds an embedding a vector id of its own. The rebuild reads every vector of the type, so on a large index it takes as long as a REBUILD INDEX: run it off-peak. In a cluster the statement runs on the leader, wherever it is issued, and the rebuilt index reaches the followers as replicated data like any other FIX of an index.

Existence constraints

Since v26.10.1 the check also asks a schema question: does every record satisfy the MANDATORY and NOTNULL constraints its own type declares? It is the one question nothing else in the database could answer, and a record that fails it is not merely untidy - every later write to it fails, because the update path validates the whole document, so the record reads as broken to the application long before anyone thinks to look at the schema.

A record can end up in that state three ways, and only the first is a fault:

Because the third is legitimate and the state it leaves is identical to the first, the removal is a clause of its own: a FIX that deleted by default would answer a DDL by destroying the type’s contents. Reporting is always on.

There are two repairs, and which one is right depends on whether the records hold data:

The two are safe to use together, including at the same time: the repair re-reads and re-checks every record inside the transaction that deletes it, so a record an UPDATE completed while the check was running is reported and left in place rather than deleted. A removal a beforeDelete trigger refuses is reported too, and not counted as removed. The removal is committed in batches sized by arcadedb.checkDatabaseRepairBatchPages, like every other CHECK DATABASE …​ FIX repair, so a bulk removal stays inside the replicated-entry limit under HA.

The pass costs nothing on a database whose types declare no such constraint: the types to scan are resolved from the schema before a record is read, so a database with none runs no pass at all and its report simply says zero.

Cached record counters

SELECT count(*) does not scan: every bucket keeps a record counter that each commit folds its delta into, and the counter is what the query answers from. That counter is persisted in the database’s statistics.json and restored when the database is opened, so a counter that goes wrong stays wrong across restarts and nothing recomputes it until something invalidates it.

Since v26.10.1 the bucket pass compares the two. It already reads every slot of every bucket, so the authoritative number is in hand, and a disagreement is reported as an error naming the bucket, both numbers and the direction:

FIX recomputes it - the counter is invalidated, and the next count() rescans and republishes it. A read-only run only reports, and the report carries staleRecordCounters and, under FIX, staleRecordCountersFixed. Both count *buckets, not records: one per bucket whose counter disagreed, whatever the size of the disagreement. They sit next to record tallies such as totalActiveRecords in the same JSON, so the distinction is worth reading twice.

This is the symptom to look for when count() disagrees with a forced full scan such as SELECT count() FROM <type> WHERE @rid IS NOT NULL, in either direction. On a replicated database the drift is per node and per bucket, so the replicas disagree with each other while holding identical data, which looks exactly like HA state divergence until a full scan rules it out.

Counters written by a release older than 26.10.1

Releases up to and including 26.9.1 could fold a replicated transaction’s record-count delta twice when a Raft entry was replayed on a node that had been restarted cleanly, which includes every rolling upgrade and every Kubernetes pod rotation. Nothing in statistics.json says which counters that happened to, so 26.10.1 does not trust any of them: the file now carries a format version, counts written without one are discarded when the database is opened, and each affected bucket recomputes on its next count(). That is one extra bucket scan, once, and the marker is written back on the next clean close. A WARNING in the server log says how many buckets it applied to, so the first count() that changes after an upgrade is not a mystery.

TimeSeries integrity

A TimeSeries type has neither record buckets nor indexes, so it is walked by a pass of its own that reads the three on-disk formats it owns: the mutable bucket (.tstb), the shared tag dictionary (.tstd) and the sealed store (.ts.sealed). The default tier reconciles every header and directory against the data it describes and verifies the CRC32 of every sealed block - which means it reads the whole sealed file, the same cost class as the record scan the check already runs over every bucket. A block is otherwise CRC-checked only on the first read that touches it, so a block nothing queries is a block nothing verifies.

DEEP adds the checks that have to decompress. A CRC proves the bytes are the bytes that were written; it proves nothing about whether they mean what the block claims. Three things every read path answers queries from, without ever looking at a value, are verified only under DEEP:

Each of those, when wrong, produces a wrong answer rather than an error, so nothing else in the engine reports it.

FIX repairs only what is derived and never a sample: the mutable bucket’s page-0 counters, the sealed header’s block count and global timestamp bounds, and the tail of an interrupted sealed append. Those matter beyond tidiness - a wrong global bound is read straight out of the header when the file is opened, so a range query pruned against it silently misses data the file holds, and a tail no reader can see also hides every block appended after it.

A sealed block that fails its CRC, or that DEEP finds inconsistent, is reported and left untouched. It is the only copy of the samples in it, so discarding it is a decision for an operator, who under HA can also rebuild a sealed store by recompacting from the replicated mutable pages.

Examples

Exports a database in the exports directory under the root directory where ArcadeDB is running.

Syntax

Examples

Executes an import of the database into the current one. Usually an import database is executed on an empty database, but it is possible to execute on any database. In case of conflict (unique index key already existent, etc.), the conflicting records will not be imported. The importer automatically recognize the file between the following formats:

Syntax

Examples

Result

The statement returns a single row with a result column: OK when the import completed, or FAIL when the source or one of the settings could not be used, in which case a reason column explains why. Any other failure raises an error.

(Since v26.10.1: the FAIL answer was overwritten with OK before it reached the client, so an import of an unusable source reported success with no rows and no statistics. Scripts that check result now detect these failures.)

See also Importer for a description of the settings.