load

sqlload load [SELECTOR ...] [OPTIONS]

sqlload load loads the selected tables, creating any that don’t exist yet. It prints the plan’s closing line and any errors and warnings, then a line per table as it finishes. It takes the same options as plan.

Loading

$ sqlload load
✓ Plan complete  2 selected, 2 objects to create, 2 to load   (sqlload plan shows the tree)

created  raw.app__customers  6 columns
created  raw.app__orders     7 columns
loaded  raw.app__customers     50 rows 0.0s
loaded  raw.app__orders     1,000 rows 0.0s

✓ Completed  2 loaded, 1,050 rows, 0.1s
└── slowest      raw.app__orders 0.0s

Each table prints created, altered, loaded or failed; a loaded line ends with the table’s new cursor position when it keeps one. A failed table doesn’t stop the others. The summary counts them, names the slowest table, and after failures says what a rerun does. The command exits 1, or 75 when every failure may pass on a rerun (see Retrying failed runs). A table the plan skips, such as a files table with no new file, isn’t read.

On a terminal, a live block under these lines shows how many tables are done, each running table with its rows so far, the tables waiting, and any rate_limit in use. It’s redrawn in place and cleared at the end. See Events for --progress.

Stopping at the first failure

From 0.43.0, --fail-fast stops the load once a table fails: no other table starts, and tables already loading finish and keep what they committed. The summary names the tables that never started under not started, and the command exits as it would have otherwise: 1, or 75 when every table that failed, including any still loading when the first failed, may pass on a rerun. A rerun loads the tables that didn’t start as usual.

$ sqlload load --fail-fast --concurrency 2
…
loaded  raw.shop__customers  400,000 rows 1.0s
loaded  raw.shop__refunds    200,000 rows 0.3s
failed  raw.shop__returns    checks.min_rows failed: 50,000 rows staged, fewer than the 100,000 required; nothing was published
loaded  raw.shop__orders     3,000,000 rows 3.0s

✗ Completed with failures  3 loaded, 1 failed, 1 not started, 3,600,000 rows, 3.1s
├── not started  raw.shop__shipments (--fail-fast)
├── slowest      raw.shop__orders 3.0s
└── next         the 2 unchanged tables load; the 3 that committed carry on from their positions

--fail-fast doesn’t combine with --follow.

Large loads commit along the way, so a failure keeps what committed and the next run carries on from there; a delete_insert into ClickHouse read by cursor publishes once per run instead. See Batches. To read a range instead of continuing from the destination’s maximum, give --start-cursor and --end-cursor; see Backfilling a range.

Reloading

--reload rebuilds tables from scratch. On a terminal it shows the plan and asks; in scripts, add --yes:

$ sqlload load --reload --yes app__customers
✓ Plan complete  1 selected, 1 object to create, 1 to load   (sqlload plan shows the tree)

loaded  raw.app__customers     50 rows 0.0s

✓ Completed  1 loaded, 50 rows, 0.1s
└── slowest      raw.app__customers 0.0s

From 0.51.0, --reload takes --start-cursor and --end-cursor, and rebuilds the table with only the rows in that range, as SQLBuild’s --full-refresh does with an interval. Rows outside the range are dropped, and plan warns which:

$ sqlload plan --reload --start-cursor 100000 --end-cursor 200000 shop__orders
…
    ├── reads   order_id from 100000 (--start-cursor), below 200000 (--end-cursor)
…
    └── commits 2 windows of 50000, read one after another into a new table, swapped in once at the end

Warnings (1)
└── shop__orders
    └── --reload rebuilds the table with only the rows from 100000 (--start-cursor), below 200000 (--end-cursor): rows before 100000 and from 200000 on are dropped

Without --start-cursor, a reload starts from cursor_start, or from the first row. An integer batch_size on a source that can’t report its maximum needs --end-cursor, with or without --reload; see Batches.

A postgres_cdc table is copied again with --resnapshot instead; --reload refuses it. See Reloading. --reload is also refused on Postgres targets.

Following a Postgres CDC source

sqlload load SOURCE --follow keeps streaming one postgres_cdc source after it catches up, writing a batch every batch_interval, until --max-duration passes or it gets Ctrl-C or SIGTERM. A second Ctrl-C or SIGTERM stops it at once, with exit code 130. See Keep streaming.

sqlload load app --follow --max-duration 10m

Results as JSON

From 0.27.0, apply --json and load --json print one JSON document on standard output when they finish, for scripts and orchestrators. Logs stay on standard error. The exit code is the same as without --json.

$ sqlload load --json
{
  "schema_version": 1,
  "command": "load",
  "ok": false,
  "retryable": true,
  "started_at": "2026-11-08T16:33:56.655Z",
  "finished_at": "2026-11-08T16:33:56.731Z",
  "duration_seconds": 0.076,
  "summary": {
    "created": 1,
    "altered": 0,
    "recreated": 0,
    "loaded": 1,
    "failed": 1,
    "skipped": 0,
    "rows": 1200
  },
  "plan": { "ok": true, "summary": "2 selected, 2 objects to create, 2 to load", … },
  "objects": [
    { "action": "created", "name": "raw.shop__orders", "detail": "4 columns" }
  ],
  "tables": [
    {
      "table": "raw.shop__orders",
      "source": "shop",
      "target": "dev",
      "write_strategy": "replace",
      "status": "loaded",
      "rows": 1200,
      "duration_seconds": 0.032,
      "note": null,
      "error": null,
      "retryable": false
    },
    {
      "table": "raw.shop__refunds",
      "source": "shop",
      "target": "dev",
      "write_strategy": "replace",
      "status": "failed",
      "rows": null,
      "duration_seconds": 0.009,
      "note": null,
      "error": "GET http://api.example.com/v1/refunds?page=3: HTTP 503: unavailable (after 4 attempts)",
      "retryable": true
    }
  ]
}

Field	Meaning
schema_version	1. New fields can appear without a change; it changes only when a field changes meaning or goes away.
command	apply or load.
ok	Whether every selected table planned and loaded: true exactly when the exit code is 0.
retryable	From 0.34.0. Whether running the command again unchanged may fix every failure: true exactly when the exit code is 75. It’s false when ok is true, whenever a table failed for good, and whenever a plan error other than an unreachable source left one out. See Retrying failed runs.
summary	How many objects were created, altered (each table once, however many changes it had) and recreated; tables loaded and failed, and from 0.43.0 skipped; rows loaded.
plan	The same document plan --json prints, with its own ok and, from 0.34.0, retryable. Tables a plan error left out are in its errors, and tables with nothing to load in skipped.
objects	One entry per change to a table or stage, by apply or during a load: its action (created, altered or recreated), its name and the detail. A table that gains two columns has two altered entries.
tables	Each table loaded: its status (loaded or failed, or from 0.43.0 skipped for a table --fail-fast didn’t start, its error naming the table that stopped the run and retryable true), rows, duration_seconds, a note (the cursor window it read, or that its table waits for first data), and the error when it failed. From 0.34.0, retryable says whether that failure may pass on a rerun. source, target and write_strategy are null only for a load --follow that failed before any table. From 0.39.0, a files source with after_load also has after_load: its action (delete or move), status (done, or failed when any file stayed), files handled, and failed, each file left with its error. A table that keeps its files has no such field. From 0.51.0, a delete_insert table with a replace_key also has replaced_keys: its columns, the values its commits replaced (sorted, each as its columns’ text joined by , , NULL for a NULL, at most 1,000) and truncated, true when there were more. apply loads nothing, so its list is empty.

When the run can’t start (the configuration doesn’t parse, a connection fails), standard output holds one error document instead, the same as plan --json’s: {"error": {"code": "config", "message": "…", "help": "…", "retryable": false}}. code is config for the configuration, else the command’s name. From 0.34.0, retryable is true, and the exit code 75, when the run couldn’t start for a reason a rerun may fix, such as a target that refused the connection or timed out.

--reload and --resnapshot need --yes with --json, as there is no prompt to answer.

Under --json, what a Python source prints goes to standard error, so standard output holds only the document. Output written to the process’s standard output directly, such as by a child process that inherits it or os.write(1, …), still reaches standard output: capture or redirect it in the source.

Events

From 0.51.0, --events jsonl writes each load event to standard error as one line of JSON, next to the logs, while it happens. --events-file PATH writes them to a file instead. Neither combines with --follow. Prefect and Dagster shows how to send them to an orchestrator’s log.

$ sqlload load --events jsonl 2>&1 >/dev/null
{"schema_version":0,"run_id":"bb60bf2a-…","at":"2026-11-14T17:05:37.263Z","event":"run_started","selected":2,"to_load":2}
{"schema_version":0,"run_id":"bb60bf2a-…","at":"2026-11-14T17:05:37.266Z","table":"raw.items","event":"table_started","strategy":"replace"}
…
{"schema_version":0,"run_id":"bb60bf2a-…","at":"2026-11-14T17:05:37.286Z","table":"raw.items","event":"table_failed","reason":"checks.min_rows failed: 1 row staged, fewer than the 1,000 required; nothing was published","retryable":false,"elapsed_ms":18}
{"schema_version":0,"run_id":"bb60bf2a-…","at":"2026-11-14T17:05:37.289Z","table":"raw.orders","event":"table_done","rows":3,"elapsed_ms":22}
{"schema_version":0,"run_id":"bb60bf2a-…","at":"2026-11-14T17:05:37.290Z","event":"run_finished","loaded":1,"failed":1,"not_started":0,"rows":3,"elapsed_ms":62,"exit_code":1}

The events are version 0: names and fields can still change in a minor release until schema_version is 1. Every event has schema_version, run_id, at (RFC 3339, UTC) and event, and a table’s events have table, named as plan names it.

event	Fields
run_started	selected, to_load: the tables selected and the tables the load starts.
table_started	strategy: the write strategy, as plan shows it.
table_progress	unit (page, batch, window or file), count of them read so far, rows so far.
rate_limited	connection, its rate_limit as rate, and wait_ms, how long a request waited. No table.
table_committing	rows: the table’s rows are read and its last commit starts.
table_done	rows, elapsed_ms, and position, the cursor value it reached, when it keeps one. changes lists the created and altered lines of a table that made or widened its columns while loading.
table_failed	reason, retryable (whether a rerun may pass), elapsed_ms.
table_not_started	reason, such as the table that stopped a --fail-fast load.
run_finished	loaded, failed, not_started, rows, elapsed_ms and exit_code.

On a terminal, load also draws a live block of running tables on standard error. The default, --progress auto, leaves it out under --json or --log-format json; --progress always draws it on a terminal anyway, and --progress never leaves it out. Output that isn’t a terminal never has the block or colours.