Skip to content
Get Started

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.