Getting Started

Prerequisites

• Python >= 3.12
• uv package manager

Install

uv init --app my-project
cd my-project
uv add barca

This installs the @asset() decorator and the barca CLI into your project’s virtualenv.

Hello world

Create pipeline.py:

from barca import asset

@asset()
def hello() -> dict:
    return {"message": "Hello from barca!"}

Run it:

uv run barca get pipeline.py

You’ll see a one-line progress summary on stderr, followed by structured JSON on stdout:

[barca] 1/1 steps done in 0.0s
{"elapsed_seconds":0.296,"final_output":{"message":"Hello from barca!"},"phases":1,"run_id":"b1b72bc4c9e3","steps_executed":1}

The @asset() decorator itself does nothing at runtime – it’s an identity function. Your code runs exactly the same with or without barca installed.

Add a dependency

Assets depend on other assets via inputs=. Barca resolves the DAG and executes them in the right order.

from barca import asset

@asset()
def raw_data() -> list[dict]:
    return [{"x": 1}, {"x": 2}, {"x": 3}]

@asset(inputs={"data": raw_data})
def summary(data: list[dict]) -> dict:
    return {"count": len(data), "sum": sum(d["x"] for d in data)}

uv run barca get pipeline.py

Barca sees that summary depends on raw_data, plans them as a single sequential chain, executes raw_data first, then passes its output to summary as the data kwarg.

See the plan

You can see what barca will do without executing anything:

uv run barca plan pipeline.py

{
  "total_steps": 2,
  "phases": [
    {
      "reason": "Initial",
      "streams": [
        {
          "stream_id": "p0-w0",
          "steps": ["pipeline.py:raw_data", "pipeline.py:summary"]
        }
      ]
    }
  ]
}

Next steps

• Guide – full tutorial covering tasks, sensors, partitions, parallel dispatch, freshness markers, and multi-file pipelines
• Scheduling – run a script on a cron schedule (e.g. every 10 minutes) with barca serve
• Patterns: Asset to Task – common patterns and anti-patterns
• CLI Reference – all CLI commands