Workflow: Single Asset, No Inputs

One asset with no inputs: what barca get does with it, what ends up on disk, and when the function runs again. Output on this page is from barca 0.30.2.

This page used to be a design specification (a .barcafiles/ directory with code.txt and metadata.json, an indexing step that imports modules, a hash that covers uv.lock and the Python version). None of that was built. What follows is what the binary does.

The asset

Save as pipeline.py in an empty directory:

from barca import asset

PREFIX = "yellow"


@asset()
def a() -> str:
    return f"{PREFIX} banana"

The decorator returns the function unchanged, so a() called from Python still returns "yellow banana".

See what barca sees

barca list pipeline.py

NAME           KIND   FRESHNESS  DEPS
-------------------------------------
pipeline.py:a  asset  always     -

Barca reads the source to find this. It does not import the file. The node id is <file>:<function>; on the command line the bare name a is enough.

Run it

barca get a pipeline.py

In a terminal:

[barca] 1/1 steps | done in 0.0s
Run 52255d4e3e20 | got 'a' in 0.138s (1 step, 1 phase)

.barca/artifacts/pipeline.py--a/62c8cf9a....json
  "yellow banana"

barca get a pipeline.py -o value prints only the value, and -o path only the path.

Piped or captured, stdout is one JSON object instead (--json forces it, --pretty forces the table). Progress stays on stderr:

{"elapsed_seconds":0.056936559,"final_output":{"_barca_artifact":{"format":"json","path":".barca/artifacts/pipeline.py--a/62c8cf9a....json","size_bytes":15}},"phases":1,"run_id":"212ddeb7e631","status":"success","steps":[{"attempts":1,"detail":"no cached result for this code and these inputs","elapsed_seconds":0.0014823181554675102,"id":"pipeline.py:a","kind":"asset","reason":"not_materialized","run_hash":"62c8cf9a...","status":"ran"}],"steps_executed":1,"warnings":[]}

Run the same command again and the function does not run:

Run 52252d1eb128 | got 'a' in 0.021s (0 steps, 1 phase)

.barca/artifacts/pipeline.py--a/....json
  "yellow banana"

In JSON the step has "status":"cached", an artifact path, and steps_executed is 0.

What is on disk

The run created .barca/ in the project root:

.barca/.gitignore
.barca/metadata.db            (plus metadata.db-wal and metadata.db.lock)
.barca/artifacts/pipeline.py--a/62c8cf9a....json
.barca/gc-state.json          (the last measurement of .barca/ against its size limit)
.barca/run-owners/            (markers for runs in flight; empty once the run ends)

• metadata.db holds run history and the record of each result.
• The artifact is the returned value, stored as json because a string is JSON-serializable (barca docs types lists the formats). It is cached by run hash: the file name is a hash of the function’s code and its inputs, not of the output.
• .barca/.gitignore contains *, so git ignores the directory.

Do not read or delete files under .barca/ by hand. Use these:

barca status pipeline.py

NAME  KIND   STATE   WHY           LAST RUN                               SHAPE  DEPS
a     asset  cached  materialized  success 2026-10-21 21:07:49 UTC 0.00s  str    -

1 cached, 0 stale, 0 never run, 0 partial, 0 unknown, 0 always run

barca sql "select * from a"

json
yellow banana

Install SQL support with uv add 'barca[sql]'. A result that is not a table (a string here) is one row with one column named json. barca history lists the runs.

When the function runs again

The run hash covers the function’s source, the decorator arguments that affect its result (barca docs cache lists them), and the module-level names it uses. Each of these was run in order after the steps above:

Change	Result
Nothing	cached, 0 steps
Add a comment at the end of the file, or a constant a does not use	cached, 0 steps
PREFIX = "green"	runs; a second artifact file appears beside the first
PREFIX = "yellow" again	cached, 0 steps: the first artifact is still there and its hash matches
barca get a pipeline.py --refresh a	runs, and overwrites the artifact for that hash

What the hash does not cover (installed packages, environment variables that are not declared with env=, files the function reads) is listed in barca docs cache. A function that reads a file or a bucket is computed once and then served from cache; see Sensors and external observations.

--no-cache was removed in 0.24.0; use --refresh-all.

Preview without running

barca get a pipeline.py --dry-run

reports each step as cached or will run with the reason, executes nothing and writes nothing. barca plan pipeline.py prints the execution plan as JSON.

From Python

import barca

barca.get("a", "pipeline.py")   # "yellow banana"

barca.get runs the barca binary and returns the deserialized value, with the same caching.

Next: one asset with one input.