Overview
A batch is a named group of .sql files, converted together inside a session, through the same 5-phase pipeline as a single-file conversion, distributed across parallel workers. A session can hold more than one batch: useful for splitting a large migration into stages without starting over each time. See Sessions & Batches for how workspaces, sessions, and batches fit together.
Two ways in
The quick 3xcode pyspark convert --dir shorthand creates and runs an implicit batch in one step. The explicit batch commands (create, add, seal, run) let you build a file list up incrementally, review it before running, or schedule the run for later.
Resumable by design
Every batch is a durable record on disk of which files completed, which failed, and where to pick up again if the CLI, your terminal, or your machine goes away mid-run.
The Batch Lifecycle
A batch moves through a small set of states: created and open, sealed, running, and a terminal state (completed, failed, or cancelled). Membership is only open before sealing.
Lifecycle commands
| Command | What it does |
|---|---|
batch create <session_id> -n NAME [-d DIR] | Creates a new, open batch, optionally adding files from a directory immediately |
batch add <session_id> <batch_id> -d DIR | Adds every `.sql` file in a directory to an open batch. Refuses once sealed |
batch seal <session_id> <batch_id> | Freezes the file list. Idempotent once sealed |
batch run <session_id> <batch_id> | Runs a sealed batch as a detached background worker; returns immediately |
batch watch <session_id> [batch_id] | Live dashboard for one batch, or every batch in a session |
batch list <session_id> | Table of every batch in a session, with state and file counts |
# Build the batch up, then run it 3xcode batch create session-abc --name "phase-1" --dir ./sql/views/ 3xcode batch add session-abc batch-phase-1 --dir ./sql/more-views/ 3xcode batch seal session-abc batch-phase-1 3xcode batch run session-abc batch-phase-1 --workers 8 3xcode batch watch session-abc batch-phase-1
batch run refuses to start a second worker if one is already live for the same batch (converting, and billing, the same files twice), and refuses to run a batch that hasn't been sealed yet. It will, however, pick back up a batch left running by a worker that crashed: files it had already started are self-healed rather than duplicated.
Adaptive Workers
The -w / --workers flag sets a ceiling on parallelism, not a fixed worker count. Left at its default, 0, a batch starts conservatively and ramps concurrency up as files keep succeeding, then backs off sharply the moment the AI provider signals it's overloaded, holding steady for a short cooldown before trying to grow again. A memory check and an automatic safety cutoff (which drops concurrency to a minimum if repeated failures suggest something is actually wrong, not just a slow moment) both act as independent ceilings underneath whatever you set -w to.
Worker flag
| Flag | Default | Behavior |
|---|---|---|
-w N / --workers N | 0 | Sets the ceiling adaptive tuning is allowed to grow to. `0` (the default) lets it grow up to a built-in cap; a positive N caps it at N. Either way, the batch can still run below that ceiling if the provider pushes back or memory is tight. |
3xcode health reports your machine's CPU and RAM as general context, but you rarely need to compute a worker count yourself: the point of adaptive tuning is that you usually don't have to.
Pause, Resume, Cancel
batch pause
Pauses a running batch. Its quota hold stays alive while paused, since the work isn't finished, just not actively running.
batch resume
Resumes a paused batch on the same run, picking up where it left off. If the pause window has expired, use batch run instead to start a fresh run against the remaining files.
batch cancel
Cancels a running batch. Already-completed files stay completed and billed; anything unfinished is released back to your quota.
3xcode batch pause session-abc batch-phase-1 3xcode batch resume session-abc batch-phase-1 3xcode batch cancel session-abc batch-phase-1 --force
Scheduling a Batch
A sealed batch doesn't have to run immediately. batch schedule --at/--in wakes it up later as a one-off background process, and the separate schedule command group adds a durable schedule that survives a reboot and can repeat. See Scheduled Conversions for the full comparison.
Reports & Metrics
Every batch writes a BATCH_SUMMARY.md report to its output directory when it finishes, alongside the usual per-file _audit.md/_audit.json reports. Read this first: it's built to be triaged, not read file by file.
What's in a BATCH_SUMMARY.md
| Section | Contents |
|---|---|
| Statistics | Total files, completed count, failed count, total cost |
| File Results | A table of every file: status, confidence, completion, cost, duration |
| Confidence & Completion Distribution | File counts per band (Low / Medium / High / Perfect) for both scales, plus each mean |
| Phase-Cost Rollup | Total cost broken down by pipeline phase (discovery, planning, conversion, validation, auto-fix) |
| Needs Attention | Batch-level flags (e.g. a large share of the batch landing in a low band) plus a per-file "Files to review" list with reasons |
cat output/<session_id>/<batch_id>/BATCH_SUMMARY.md 3xcode session info <session_id>
Bands, not just a pass/fail count
Confidence and completion are each banded (Low <70, Medium 70-89.99, High 90-99.99, Perfect =100), so you can see the shape of a batch's quality at a glance. See Billing & Quota for exactly how bands are defined.
One report per batch
Splitting a migration into multiple batches (see Sessions & Batches) gives you one BATCH_SUMMARY.md per stage, so you can track quality and cost stage by stage instead of only at the end.
Session Command Reference
The 3xcode session command group manages the container a batch lives in. Running bare 3xcode session with no subcommand defaults to session list.
session subcommands
| Command | Key flags | What it does |
|---|---|---|
session create | -n/--name, -d/--dir, --model | Creates a new session, optionally for a directory of SQL files, without immediately starting a conversion run. |
session list | None | Table of sessions in the active workspace: ID, name, state, file counts, cost, created date. Also the default action of bare `session`. |
session info <id> | None | Full session summary (name, state, model, file counts, cost, duration, success rate) plus a per-file table with status, cost, duration, and any error message. |
session resume <id> | --model, -v/--verbose | Resumes an interrupted or partially-completed session, converting only files that haven't completed yet. |
session status <id> | -w/--watch | Live status: per-status file counts, running worker's current phase/file/heartbeat, per-phase durations, and an ETA estimate. `--watch` tails live events in real time. |
session pause <id> / cancel <id> | -f/--force | Pauses or cancels a running session cleanly: completed files stay completed. |
session rename <id> <new_name> | None | Renames a session without touching its ID or any converted output. |
session delete <id> | -f/--force | Deletes a session's input/output/log files. Refuses if a worker is currently running for it. Cancel first. |
session list-all | None | Lists currently-running sessions across every registered workspace on the machine, not just the active one. |
Where Files Land
Sessions and batches live inside a workspace, and 3xcode workspace init <path> --name <name> lays down the standard layout everything reads from and writes to:
input/
Source SQL files for the workspace's conversions.
output/<session_id>/<batch_id>/
Per-batch output: generated PySpark modules under pyspark/*.py, JSON phase artifacts under reports/, a per-file *_audit.md and *_audit.json, and the batch's BATCH_SUMMARY.md report.
.sessions/
Durable session and batch state and event logs: this is what makes resume, status, watch, and cancel work across process restarts.
logs/
Workspace-level logs. workspace status reports session counts, file counts, and the last session ID for the active workspace at a glance.
Use 3xcode workspace list to see every registered workspace on the machine and which one is active, workspace switch to move between projects, and workspace status for a quick summary of the active workspace's sessions and file counts. session status, session cancel, session delete, and session rename all resolve sessions across every registered workspace, not just the active one.