All Pages (A–Z)
Every page on this site except design records and contributor notes, sorted by name. Press
⌘K (CtrlK) to search instead, or run barca docs <topic> for the
same material in your terminal.
A
- Agent SkillReference
SKILL.md, the short guide an AI coding agent loads once before it runs barca commands.
- Anti-Patterns to AvoidRecipe
Things that fail or give stale or wrong results in barca, what happens on current barca (rechecked on 0.42.0), and what to do instead.
- ArchitectureGuide
The crates, modules, worker protocol and storage that make up barca.
- Architecture DecisionsGuide
The main decisions in barca's execution engine, what was tried first, and what was rejected.
- Assets, Sensors and InputsReference
@asset and @sensor: inputs, freshness, retries, environment variables, heavy steps and how a node is identified.
- Authentication and TokensGuide
Require a token on barca serve: turn it on, connect the web UI with a one-use code, create API tokens for laptops and scripts, and revoke them. Login, authentication, access control.
B
- barca docsReference
The built-in manual, for the installed version.
- barca doctorReference
Check project prerequisites, stores and credential identity without running steps.
- barca gcReference
Evict cached results to keep .barca/ under its size limit (experimental).
- barca getReference
Get assets, from cache when nothing changed; prints where their results are.
- barca historyReference
Show recent runs, or one run with its steps and errors.
- barca listReference
List the assets, tasks and sensors barca finds, with their inputs.
- barca logsReference
barca logs: a run's recorded step stdout and stderr, following a live run, and how lines are kept.
- barca pause and resumeReference
Containing an incident: barca pause and barca resume, and what scheduled runs and requests do with a paused asset.
- barca pin and unpinReference
barca pin and unpin: roll an asset back to an earlier materialization, held for every run until unpinned.
- barca planReference
Print the execution plan as JSON without running anything (experimental).
- barca queueReference
A server's run queue; pause or resume it (experimental).
- barca runReference
Run tasks. A task always runs; the assets it reads come from cache.
- barca serveReference
Run the HTTP API, the cron scheduler and the web UI.
- barca sqlReference
barca sql: query cached results with DuckDB while debugging, without writing a step.
- barca stateReference
List the metadata backups, put one back, or start the database over.
- barca statsReference
Timing and cache statistics for one asset.
- barca statusReference
barca status: every node's cache state and why, its last run, its artifact's shape, --problems and --state.
- barca status: Fields and JSONReference
What barca status reports for each node beyond its state (last materialization, artifact shape, run timing, trigger), its JSON document, limits and disk usage.
- barca tokensReference
Print a one-use code to connect the web UI or a laptop to a server that runs with --auth token (experimental).
- barca versionReference
Print the installed version.
- Barca vs Cron and systemd TimersComparison
What a scheduled job gets from a crontab line, a systemd timer, and a barca Schedule under barca serve, feature by feature.
- Barca vs DagsterComparison
Install size, steps to a first result, run time, run output and error output for the same two-asset pipeline, measured on 2026-10-21 with barca 0.28.0 and Dagster 1.13.26.
- Barca vs PrefectComparison
Install size, import time, steps to a first result, run time, run output, error output and caching for the same pipeline, measured on 2026-10-21 with barca 0.28.0 and Prefect 3.9.0.
- Batched PartitionsReference
batch=: one call of a partitioned step computes many keys; grouping, the batch function, what stays the same, calls and known limits.
- Branch or Stop ConditionallyRecipe
Barca has no conditional construct. Branch inside the function body, or raise in a gate step to stop what depends on it.
C
- Chain AssetsRecipe
Chain assets with inputs=. Each step is cached and runs again only when its code or an upstream changes.
- CLI ContractReference
Every barca command, flag, environment variable, exit code and JSON schema, marked stable or experimental, and the policy for changing them.
- CLI ReferenceReference
Every barca command with its arguments, flags, defaults and output.
- ConfigurationReference
Every barca.toml key and environment variable, their precedence, what is under .barca/, and how --env separates environments.
- Core ConstraintsGuide
The rules barca was designed around, which of them 0.42.0 implements, and what happens where it does not.
D
- Decorators APIReference
Arguments and behavior of @asset, @sensor, @task, @sink and @unsafe, the freshness markers, partitions, parallel() and the other names barca exports.
- Deploying barca serveGuide
Run barca serve as a long-lived service, in a container or behind nginx or Traefik, and what happens on restart.
- DiscoveryReference
Which files make up a barca project: the root, tree walks, [discovery] in barca.toml, and node ids.
- Disk UseReference
The size limit for .barca/, what barca gc evicts and in which order, and how the metadata database keeps to its share.
- DuckDB VersionsReference
duckdb 1.x and 2.x: what a pipeline must change for duckdb 2, and why a database file duckdb 2 writes cannot be opened by 1.x.
E
- Exit Codes and ErrorsReference
What barca's exit codes 0, 1, 2, 3 and 130 mean, the JSON error envelope on stderr, and how a script or agent should read a failure.
- External Data and Early CutoffReference
Rerun a step when a file or table changes in place by reading it through a @sensor, and keep what is downstream cached with @asset(cutoff=True).
F
- Feed an Asset to a TaskRecipe
An asset produces a cached value; a task reads it and does something with it. The task runs every time.
- Forcing a RecomputeReference
barca get --refresh, --refresh-all and --no-cascade: what reruns, refreshing selected partition keys, Manual upstreams, and --dry-run.
- Freshness and SchedulesWorked example
What the freshness argument does. Schedule fires a node under barca serve, Always nodes below it follow its ticks, and a Manual node is refreshed by hand only.
G
- Getting StartedGuide
Run cached assets, tasks and partitions locally, then run the same project on a server.
- GroupsReference
Organize pipeline nodes in the UI and CLI without changing execution or caching.
- Guide: Beyond the First RunGuide
Where results live, how to see what is cached and why, and how sensors, tasks, partitions and projects with several files work.
H
- Helpers APIReference
partitions, partitions_from, collect, asset_ref, @sink, parallel and parallel_map, qualified imports, and the other names barca exports.
M
- Metadata BackupsReference
Backups of the metadata database in the store, barca state backups and barca state restore, and how a server's backups differ.
O
- One Asset, No InputsWorked example
One asset with no inputs, rechecked with barca 0.42.0. What is written to disk, when it is served from cache, and how to look at the result.
- One Asset, One InputWorked example
One asset that reads another, rechecked with barca 0.42.0. What runs after each kind of change, and what --refresh and --no-cascade do.
- Operating barca serveReference
Operating barca serve: the run queue, stopping and restarting without losing work, the stop grace a supervisor needs, a shared capacity and the run timeout.
- Output Formats and TypesReference
json, pickle, parquet and CSV artifacts, and how annotations pick readers (pandas, polars, pyarrow, duckdb).
P
- PartitionsReference
Fan-out over keys and fan-in with collect: updating only what changed, batched calls, failed keys and selecting keys.
- Partitions, Step by StepWorked example
One asset definition run once per key, each key cached on its own. What runs when keys, code or a sensor change, how to look at the results, and the limits on 0.30.2.
- PhilosophyGuide
The design goals behind barca, the reason for each, and what each one costs.
R
- Read Large Inputs LazilyRecipe
A parquet input with no annotation is read whole with pandas. Annotate it as a DuckDB relation or a polars LazyFrame to read only what the step uses.
- Release NotesGuide
What changed in each barca release, newest first, including breaking changes and how to upgrade. The same text as CHANGELOG.md and the GitHub releases.
- Remote StorageReference
Keep results and backups of the run history in S3, GCS, Azure or Cloudflare R2, configured with environment variables; restore the history with one command.
- Renaming and Moving an AssetWorked example
What happens to an asset's cache and history when its function is renamed or its file is moved, with and without an explicit name=, rechecked on barca 0.42.0.
- Rerun Only Changed PartitionsRecipe
One sensor query returns every key and its version; partitions_from over that dict runs only the keys whose version changed, through a chain of partitioned assets.
- Retries, Timeouts and FailuresRecipe
Declare retries and a timeout on the decorator. A step that still fails stops the steps that depend on it and the command exits 1.
- Run After a Step Without Its ValueRecipe
Start an input's name with an underscore when a step must run after another but does not need its value.
- Run Reports and Missing ArtifactsReference
What barca get and barca run report for each step, recompute byte checks, and what happens when a cached result's file is gone.
- Run Tasks in ParallelRecipe
Inside a task, parallel() and parallel_map() run other tasks in separate worker processes and return their results in order.
S
- Same Pipelines in Four ToolsComparison
The same small pipelines written for barca, Dagster, Prefect and Airflow, a feature list, and run times measured with barca 0.39.4 on 2026-11-04 and Dagster 1.13.26, Prefect 3.9.0 and Airflow 3.3.2 on 2026-10-21.
- Scheduling With CronGuide
Run assets, tasks and sensors on a cron schedule with barca serve, what a tick does, how Always and Manual nodes below a schedule behave, and what happens when ticks fail.
- Scripts and AI AgentsReference
The output contract for scripts and AI agents: JSON on stdout, the error envelope, exit codes, bounded output and a safe editing loop.
- Sensors and Outside DataWorked example
A sensor reports the version of data that lives outside the graph, so the assets that read that data re-run when it changes.
- Server APIReference
Start, follow and cancel runs on barca serve over HTTP, read their outcomes, and call it from Python. Every route is on Server API Endpoints.
- Server API EndpointsReference
Every route of barca serve's HTTP API, with inspection, health, state, the run queue, stopping, read-only mode, scheduling and limits.
- Server Mode: a Shared Ledger and --serverReference
One barca serve as the team's ledger: laptops read its cache hits and post their runs, and --server runs a command on it.
- Server OverviewGuide
What barca serve does, and which page answers which question: schedules, sharing results with a team, deploying, operating, the HTTP API and alerts.
- Share Results With a TeamGuide
One barca serve and one bucket give a whole team the same cache and run history, in three steps.
- SinksReference
@sink exports results to local or remote paths, as one file or a partitioned dataset.
- Slack AlertsReference
Post to Slack when a job starts failing, recovers, or is still failing a day later, with BARCA_SLACK_WEBHOOK_URL.
T
- TasksReference
@task and barca run: steps that always run, ordering-only dependencies, fan-out from inside a task, and what is recorded.
- Tasks, Step by StepWorked example
A task does something (deploy, notify, migrate), always runs, and is run with barca run. A worked example with real output.
- Telemetry (Datadog)Reference
Report every step and every run to Datadog as a trace of its own, and barca serve as DogStatsD metrics and JSON logs.
- The CacheReference
What the run hash covers, artifacts, --refresh and --refresh-all, early cutoff, dry runs, environments and what a run reports.
- The Run HashReference
Which project code a step's run hash follows from its function, which decorator arguments count, and what barca does not follow.
- The Web UIGuide
What barca serve's web UI shows and does: the health of every scope and its causes, assets and their states, runs and why they ran, the key explorer for partitions, incidents, and API tokens.
- Timeouts and CancellingWorked example
Timeouts, retries and cancellation as they work in barca 0.42.0. Ad hoc runtime parameters are not implemented.
W
- Where Things LiveReference
The project root, the .barca/ directory, concurrent runs, killed runs and upgrading.
- Why Did (or Didn't) It Run?Guide
Common surprises (stale data, a file or CSV that changed but did not rerun): an asset that did not rerun after its data, an environment variable or an option changed; a step that reran when nothing seemed to change; and how to ask barca why.