Command Line Interface (CLI)
Kùzu provides a CLI shell through which you can issue Cypher queries or CALL commands to query
metadata. See the installation docs for instructions on how
to install the CLI and the quick start page for its basic usage.
Start the shell
Kùzu supports on-disk, as well as in-memory databases. The functionality of the CLI is identical for both on-disk and in-memory modes.
On-disk database
You can create an on-disk database in the CLI by specifying a path after
the kuzu command in the terminal. This opens the database on-disk, in read-write mode, and the
data is persisted to disk after the CLI shell is closed. Note that if the database
directory does not exist, it will be created for you.
$ kuzu ./test_dbOpened the database at path: ./test_db in read-write mode.Enter ":help" for usage hints.kuzu>In-memory database
Alternatively, you can create an in-memory database by omitting the path entirely, and just calling kuzu
from your terminal:
$ kuzuOpened the database under in-memory mode.Enter ":help" for usage hints.kuzu>Shell commands
Once you start the shell, you can issue Cypher queries as shown in the get started
section. List all available shell commands by running ./kuzu -h.
$ ./kuzu -h ./kuzu [databasePath] {OPTIONS}
KuzuDB Shell
OPTIONS:
databasePath Database path. -h, --help Display this help menu -d, --default_bp_size, --defaultbpsize Size of buffer pool for default and large page sizes in megabytes --no_compression, --nocompression Disable compression -r, --read_only, --readonly Open database at read-only mode. -p, --path_history Path to directory for shell history -v, --version Display current database version -m, --mode Set the output mode of the shell -s, --no_stats, --nostats Disable query stats "--" can be used to terminate flag options and force all following arguments to be treated as positional options:help
Show built-in command list within the Kùzu shell.
kuzu> :help :help get command list :clear clear shell :quit exit from shell :max_rows [max_rows] set maximum number of rows for display (default: 20) :max_width [max_width] set maximum width in characters for display :mode [mode] set output mode (default: box) :stats [on|off] toggle query stats on or off
Note: you can change and see several system configurations, such as num-threads, timeout, and progress_bar using Cypher CALL statements. e.g. CALL THREADS=5; or CALL current_setting('threads') return *; See: https://docs.kuzudb.com/cypher/configuration:clear
Clear shell. Alternatively, you can use Ctrl + L to clear the shell.
:quit
Exit from shell. Alternatively, you can use Ctrl + D to exit the shell.
:max_rows [max_rows]
Set maximum number of rows for display. 0 defaults to 20.
:max_width [max_width]
Set maximum width in characters for display. Defaults to terminal width if unable to display first and last columns.
:mode [mode]
Set output mode. The default mode is box. See the output modes section below for more details.
:stats [on|off]
Toggle query statistics on or off. The default is on. Query statistics include the number of tuples, columns, and execution time.
Interrupt shell
To interrupt a running query, use Ctrl + C in CLI. Note: We currently don’t support interrupting a running COPY statement.
Non-interactive usage
You can also read and process a file in non-interactive mode via the CLI. Consider that you have the following DDL file:
CREATE NODE TABLE Person (name STRING, age INT64, PRIMARY KEY(name));COPY Person FROM 'person.csv';Pipe the file content to the CLI as follows:
./kuzu testdb < schema.cypherOpened the database at path: ./test_db in read-write mode.Enter ":help" for usage hints.┌────────────────────────────────┐│ result ││ STRING │├────────────────────────────────┤│ Table Person has been created. │└────────────────────────────────┘(1 tuple)(1 column)Time: 0.04ms (compiling), 0.82ms (executing)┌────────────────────────────────────────────────┐│ result ││ STRING │├────────────────────────────────────────────────┤│ 4 tuples have been copied to the Person table. │└────────────────────────────────────────────────┘(1 tuple)(1 column)Time: 0.09ms (compiling), 11.75ms (executing)Query progress
For queries that might take a significant amount of time to execute, a progress bar can be enabled that displays the number of pipelines that have been executed (each query is broken down into one or more pipelines), as well as the percentage of the data processed in a pipeline. This gives an estimate for how much of a pipeline has executed.
The progress bar is not enabled by default. To enable the progress bar, use the following command:
CALL progress_bar=true;To further configure the progress bar, see the configuration section.
Output modes
The :mode [mode] command allows you to change the appearance of the tables returned by queries.
To view the available modes, use the :mode command without any arguments:
kuzu> :modeAvailable output modes: box (default): Tables using unicode box-drawing characters column: Output in columns csv: Comma-separated values html: HTML table json: Results in a JSON array jsonlines: Results in a NDJSON format latex: LaTeX tabular environment code line: One value per line list: Values delimited by "|" markdown: Markdown table table: Tables using ASCII characters tsv: Tab-separated values trash: No outputTo change the output mode, use the :mode command followed by the desired mode:
kuzu> :mode jsonmode set as jsonkuzu> CREATE NODE TABLE Person (name STRING, age INT64, PRIMARY KEY(name));[{"result":"Table Person has been created."}]The :max_rows and :max_width commands can be used to control the number of rows and the width
of the box, column, table, and markdown output modes.