System ops

System ops start with a double-colon :: and must appear alone in a script. In the following, we explain what each system op does, and the arguments they expect.

Explain

::explain { <QUERY> }

A single query is enclosed in curly braces. Query options are allowed but ignored. The query is not executed, but its query plan is returned instead. Currently, there is no specification for the return format, but you can decipher the result after reading Query execution.

Ops for stored relations

::relations

List all stored relations in the database.

::columns <REL_NAME>

List all columns for the stored relation <REL_NAME>.

::indices <REL_NAME>

List all indices for the stored relation <REL_NAME>.

::describe <REL_NAME> <DESCRIPTION>?

Describe the stored relation <REL_NAME> and store it in the metadata. If <DESCRIPTION> is given, it is stored as the description, otherwise the existing description is removed. The description can be shown with ::relations. It serves as the documentation and signpost for humans and AI.

::remove <REL_NAME> (, <REL_NAME>)*

Remove stored relations. Several can be specified, joined by commas.

::rename <OLD_NAME> -> <NEW_NAME> (, <OLD_NAME> -> <NEW_NAME>)*

Rename stored relation <OLD_NAME> into <NEW_NAME>. Several may be specified, joined by commas.

::index ...

Manage indices. See Stored relations & transactions for more details.

::hnsw ...

Manage HNSW indices. See Proximity search for more details.

::show_triggers <REL_NAME>

Display triggers associated with the stored relation <REL_NAME>.

::set_triggers <REL_NAME> ...

Set triggers for the stored relation <REL_NAME>. This is explained in more detail in Stored relations & transactions.

::access_level <ACCESS_LEVEL> <REL_NAME> (, <REL_NAME>)*

Sets the access level of <REL_NAME> to the given level. The levels are:

• normal allows everything,
• protected disallows ::remove and :replace,
• read_only additionally disallows any mutations and setting triggers,
• hidden additionally disallows any data access (metadata access via ::relations, etc., are still allowed).

The access level functionality is to protect data from mistakes of the programmer, not from attacks by malicious parties.

Monitor and kill

::running

Display running queries and their IDs.

::kill <ID>

Kill a running query specified by <ID>. The ID may be obtained by ::running.

Maintenance

::compact

Instructs Cozo to run a compaction job. Compaction makes the database smaller on disk and faster for read queries.