TypeDB Loader Reference

Reference for every command-line flag accepted by the TypeDB Loader, grouped by topic.

On resume (--resume PATH), every flag in this document — except --schema-file and --create-db, which are inert on resume — defaults to the value stored in the checkpoint unless explicitly overridden on the command line. Defaults shown below are the fresh-run defaults; on resume, the "default" is whatever the previous run used.

Connection

--address <host:port[,host:port]>

TypeDB server address(es) to connect to. Accepts either a single host:port or a comma- separated list. Also available under the alias --addresses.

Required. No default.

--username <username>

Username for authentication.

Required. No default.

--password <password>

Password for authentication.

If omitted, the loader prompts on stdin (without echo).

--tls-disabled[=true|false]

Disable TLS encryption on the wire. Defaults to false (TLS enabled).

--tls-root-ca <path>

Path to a custom TLS root CA certificate for the connection.

Database and schema setup

--database <name>

Database to load into.

Required. No default.

--schema-file <path>

Path to a TypeQL schema file to apply in a schema transaction before any data loading.

Ignored (with a warning) when resuming.

--create-db[=true|false]

Create the database if it does not already exist. Defaults to false.

Ignored (with a warning) when resuming.

Data and query

--query <path to .tql>

Path to the TypeQL query template used for loading. The query’s given variables are bound to CSV columns by name.

Required. No default.

--data <path to .csv>

Path to the CSV file to load.

Required. No default.

--header[=true|false]

Whether the CSV file has a header row. Defaults to false.

With --header true, the first row is used as the column-name → given-variable mapping. With --header false, columns are bound positionally in the order declared in given.

--no-header

Force header parsing off. Use this to override a checkpoint that had --header true set. Mutually exclusive with --header.

--null-values <value>

A string value in the CSV to treat as null. May be repeated to specify multiple sentinels (e.g. --null-values '' --null-values NULL --null-values NA).

Defaults to treating only empty cells as null.

Replaces, not extends. As soon as you pass --null-values NA, empty cells stop being null unless you also pass --null-values '' explicitly.
--max-rows <n>

Process at most n data rows. Defaults to all rows.

Pass --max-rows 0 to clear an inherited cap on resume (the value persists in the checkpoint otherwise).

Batching and parallelism

--batch-rows <n>

Number of CSV rows submitted in each query_with_inputs invocation. Each batch is committed in its own write transaction. Defaults to 1000.

Cannot be changed on resume. The loader’s cursor depends on the original batch size; a resume that passes a different value is rejected with an error.
--parallel-batches <n>

Maximum number of batches submitted concurrently to the server. Defaults to 1 (no parllelism).

Higher values increase throughput at the cost of more concurrent write transactions, which can cause commit conflicts. Tune in tandem with --batch-rows.

Output directory

The loader writes three artifacts into a single output directory: checkpoint.json, rejects.csv (rejected rows, reloadable as-is once their cause is fixed), and rejects.log (per-rejection error message). The rejects files are only created when at least one row is rejected.

--output-dir <path>

Directory to write the loader’s output into. Created if it does not already exist.

Defaults to loader_<data-stem>_progress alongside the data file.

Cannot be combined with --resume, as resuming re-uses the existing output directory.

Error handling

--stop-on-error[=true|false]

Abort on the first row or batch error, instead of skipping and continuing. The offending rows are still written to the rejects file before exit. Defaults to false.

--no-stop-on-error

Force stop-on-error off. Use this to override a checkpoint that had it enabled. Mutually exclusive with --stop-on-error.

--max-rejects <n>

Abort once the total number of rejected rows exceeds this threshold. Applies independently of --stop-on-error.

Defaults to unlimited.

Checkpointing and resume

--no-checkpoint

Disable checkpointing entirely. The loader writes no checkpoint file and the run is not resumable. Defaults to false.

Mutually exclusive with --resume.

A fresh run aborts if a checkpoint.json already exists in the chosen output directory; pass --resume <dir> to continue from it, --output-dir <other> to write elsewhere, or --no-checkpoint to disable checkpointing.

--resume <path to previous output directory>

Resume a previous run by pointing at its output directory (the one that contains checkpoint.json). Parameters from the checkpoint are used unless explicitly overridden on the command line.

A resumed run never re-applies the schema or creates the database — --schema-file and --create-db are ignored with a warning if supplied.

The loader presents a confirmation prompt before resuming if:

  • the data file’s hash differs from the checkpoint, or

  • the live TypeDB schema’s hash differs from the checkpoint, or

  • the checkpoint records any batches that were in flight when the previous run stopped (the loader prints the first row of each so you can decide whether to re-process them).

Help and version

-h, --help

Print the auto-generated help message and exit.

-V, --version

Print the loader version and exit.

Exit codes

Code Meaning

0

The run completed; all batches finished. The presence of rejects does not change this.

1

General error (I/O failure, query parse failure, internal panic).

2

User-input error (bad/missing flags, invalid combinations, hard checkpoint mismatch).

3

Connection error (could not reach or authenticate against the server).

130

Forced exit after a second Ctrl+C — sent only if the user interrupts the graceful drain.

Resume behaviour summary

A few cross-cutting rules to keep in mind when reading the per-flag entries above:

  • On resume, every flag’s effective value is cli arg if provided, else checkpoint value.

  • --batch-rows is the one exception: it cannot differ from the checkpoint.

  • --schema-file and --create-db are ignored on resume.

  • --no-checkpoint cannot be combined with --resume.

  • --output-dir cannot be combined with --resume, as it re-uses the existing output directory

  • --max-rows 0 is a sentinel that clears an inherited cap; any other value sets a new cap.

  • The --no-X opt-out flags (--no-header, --no-stop-on-error) exist solely so a resume can override a checkpoint that had the corresponding flag enabled.