# 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)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 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)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)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)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)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)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)Help and version

`-h`, `--help`

Print the auto-generated help message and exit.

`-V`, `--version`

Print the loader version and exit.

## [](#_exit_codes)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)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.
    

[Migrating a SQL Database](../sql-example/index.md) [TypeQL Syntax Checker](../../typeql-check/index.md)

[Edit on GitHub](https://github.com/typedb/typedb-docs/edit/3.x-development/tools/modules/ROOT/pages/loader/reference.adoc) Edit this page on GitHub.