Skip to main content

WORKING WITH DATA

In this tutorial, we will create two behaviors, wire one's output into the other using a data.latest() expression, run them through a workflow, then query and inspect the versioned data they produce.

What we will build

We are going to set up two command/shell behaviors. The first collects system information. The second reads the first's output and produces a summary. We will connect them in a workflow, run it, then explore what ended up in The Swamp — listing data, reading specific artifacts, querying across behaviors, and looking at version history.

Prerequisites

  • Swamp installed (see Install Swamp)
  • A terminal open in an empty directory

Sign in

Every Swamp command needs a swamp-club.com account, so we sign in first:

$ swamp auth login

Your browser opens at swamp-club.com. Once you sign in, the terminal shows Authenticated with your username. If you are already signed in, skip this step.

Initialize the repository

First, we create a fresh Swamp repo:

$ mkdir data-tutorial
$ cd data-tutorial
$ swamp repo init --tool none

You will see the Swamp banner followed by:

Initialized swamp repository at ... (tools: none)
Created vault default (local_encryption) for secrets and sensitive outputs
...

Create the first behavior

We create a behavior called system-info that runs uname -a:

$ swamp behavior create command/shell system-info
Created: system-info (command/shell)
Path: .../models/command/shell/system-info.yaml
Version: 2026.02.09.1

Methods:
  execute - Execute the shell command and capture stdout, stderr, and exit code
    Inputs:
      run (string) *required
      ...

Now we edit the definition to set the command. Open the YAML file shown in the Path line above — or use swamp behavior edit system-info — and set the run global argument:

globalArguments:
  run: "uname -a"

Run the first behavior

$ swamp behavior run system-info execute

You will see a progress tree, then output like:

   Resolved   system-info (command/shell)
  Executing   execute · 04:03:30 UTC
              Darwin Mac.localdomain 27.0.0 ...

  Completed   execute on system-info succeeded in 24ms · 04:03:30 UTC

    ┌──────────────────────────────────────────────────────────┐
    │ Arguments                                                │
    │    run   uname -a                                        │
    │                                                          │
    │ Data produced                                            │
    │  result                                                  │
    │    exitCode     0                                        │
    │    executedAt   2026-10-14T04:03:30.565Z                 │
    │    command      uname -a                                 │
    │    durationMs   13                                       │
    │    stdout       Darwin Mac.localdomain 27.0.0 Darwin...  │
    │    stderr                                                │
    │                                                          │
    └──────────────────────────────────────────────────────────┘

The behavior ran uname -a and stored the result. Let us look at what it produced:

$ swamp data list system-info
Data for system-info (command/shell)

file (1 item):
  log  v1  text/plain  156B  ...

resource (1 item):
  result  v1  application/json  262B  ...

report (2 items):
  report-swamp-method-summary  v1  text/markdown  547B  ...
  report-swamp-method-summary-json  v1  application/json  2.7KB  ...

Notice three kinds of data: a file (the raw log output), a resource (the structured JSON result), and report entries (summaries generated automatically). We will work with the result resource.

Read the data

$ swamp data query 'behaviorName == "system-info" && name == "result" && isLatest' \
    --single --json --select content
{
  "exitCode": 0,
  "executedAt": "...",
  "command": "uname -a",
  "durationMs": 13,
  "stdout": "Darwin Mac.localdomain 27.0.0 ...",
  "stderr": ""
}

The quoted predicate picks out one artifact: the latest version of result from system-info. --single insists on exactly one match, and --select content prints only the data the behavior produced. We will come back to predicates when we query across behaviors.

Create a behavior that reads another behavior's data

Now we create a second behavior that reads from system-info. This is where data.latest() comes in:

$ swamp behavior create command/shell summariser

Open the new definition file (swamp behavior edit summariser) and set the run global argument to a CEL expression that reads the first behavior's output:

globalArguments:
  run: "echo \"System: ${{ data.latest('system-info', 'result').attributes.stdout }}\""

The ${{ }} marks a CEL expression. data.latest('system-info', 'result') fetches the latest version of system-info's result data. .attributes.stdout reads the stdout field from it.

Now run it:

$ swamp behavior run summariser execute
   Resolved   summariser (command/shell)
  Executing   execute · 04:03:39 UTC
              System: Darwin Mac.localdomain 27.0.0 ...

  Completed   execute on summariser succeeded in 23ms · 04:03:39 UTC

    ┌──────────────────────────────────────────────────────────┐
    │ Arguments                                                │
    │    run   echo "System: Darwin Mac.localdomain 27.0.0...  │
    │                                                          │
    │ Data produced                                            │
    │  result                                                  │
    │    exitCode     0                                        │
    │    executedAt   2026-10-14T04:03:39.208Z                 │
    │    command      echo "System: Darwin Mac.localdomain...  │
    │    durationMs   12                                       │
    │    stdout       System: Darwin Mac.localdomain 27.0....  │
    │    stderr                                                │
    │                                                          │
    └──────────────────────────────────────────────────────────┘

Swamp resolved the data.latest() expression before running the command. The summariser read system-info's output from The Swamp without either behavior knowing about the other.

Connect them in a workflow

We have been running behaviors one at a time. Now we wire them into a workflow so they run together:

$ swamp workflow create info-pipeline
Created: info-pipeline
Path: .../workflows/workflow-info-pipeline.yaml

Open the workflow file (swamp workflow edit info-pipeline) and replace its contents with:

id: <keep the id from the generated file>
name: info-pipeline
description: Gather system info and summarise it
jobs:
  - name: main
    description: Run both behaviors in sequence
    steps:
      - name: gather
        description: Collect system information
        task:
          type: behavior
          behavior: system-info
          methodName: execute
      - name: summarise
        description: Summarise the gathered data
        dependsOn:
          - step: gather
            condition:
              type: succeeded
        task:
          type: behavior
          behavior: summariser
          methodName: execute

Notice the dependsOn entry on the summarise step — it waits for the gather step to succeed before starting. Each dependency is an object with a step name and a condition specifying when to trigger (here, type: succeeded).

Validate the workflow:

$ swamp workflow validate info-pipeline
Validating: info-pipeline
  ✓ Schema validation
  ✓ Unique job names
  ✓ Unique step names in job 'main'
  ✓ Valid job dependency references
  ✓ Valid step dependency references in job 'main'
  ✓ No cyclic job dependencies
  ✓ No cyclic step dependencies in job 'main'
  ✓ Step inputs for 'gather' in job 'main' (system-info.execute)
  ✓ Step inputs for 'summarise' in job 'main' (summariser.execute)
  ✓ GlobalArgument input references for 'gather' in job 'main' (system-info.execute)
  ✓ GlobalArgument input references for 'summarise' in job 'main' (summariser.execute)
Summary: 11 passed
Result: PASSED

Now run it:

$ swamp workflow run info-pipeline
 system │ Starting workflow info-pipeline · 04:03:57 UTC

   main │ start 04:03:57 UTC
   main │ step gather · system-info · execute · start 04:03:57 UTC
   main │ Darwin Mac.localdomain 27.0.0 ...
   main │ done gather in 40ms · 04:03:57 UTC
   main │ step summarise · summariser · execute · start 04:03:57 UTC
   main │ System: Darwin Mac.localdomain 27.0.0 ...
   main │ done summarise in 30ms · 04:03:57 UTC
   main │ completed in 75ms · 04:03:57 UTC

 system │ Completed workflow info-pipeline succeeded in 84ms · 04:03:57 UTC

    ┌───────────────────────┐
    │ Data produced         │
    │  result    from main  │
    │  result    from main  │
    │                       │
    └───────────────────────┘

Both behaviors ran in sequence. We can see the workflow-scoped data:

$ swamp data list --workflow info-pipeline
Data for workflow info-pipeline (run ...)

file (2 items):
  log  v2  system-info  main.gather  156B
  log  v2  summariser  main.summarise  164B

resource (2 items):
  result  v2  system-info  main.gather  262B
  result  v2  summariser  main.summarise  425B

report (6 items):
  ...

Notice the version numbers — result v2 for system-info because we have run it twice now (once manually, once through the workflow).

Query across behaviors

So far we have looked at data one behavior at a time. swamp data query searches across everything in The Swamp using CEL predicates:

$ swamp data query 'tags.type == "resource"'
┌────────┬─────────────┬──────────┬──────────┬─────────┬──────┐
│ name   │ modelName   │ specName │ dataType │ version │ size │
├────────┼─────────────┼──────────┼──────────┼─────────┼──────┤
│ result │ system-info │ result   │ resource │ 2       │ 262B │
├────────┼─────────────┼──────────┼──────────┼─────────┼──────┤
│ result │ summariser  │ result   │ resource │ 2       │ 425B │
└────────┴─────────────┴──────────┴──────────┴─────────┴──────┘

2 results

The predicate tags.type == "resource" matched every resource across both behaviors. We could also query by behavior name (behaviorName), content type, or any tag.

View version history

Every time a behavior runs, it creates a new version of its data. Let us see system-info's version history:

$ swamp data versions system-info result

You will see output like:

{
  "dataName": "result",
  "modelId": "...",
  "modelName": "system-info",
  "modelType": "command/shell",
  "versions": [
    {
      "version": 2,
      "createdAt": "...",
      "size": 262,
      "checksum": "...",
      "isLatest": true
    },
    {
      "version": 1,
      "createdAt": "...",
      "size": 262,
      "checksum": "...",
      "isLatest": false
    }
  ],
  "total": 2
}

Two versions — one for each time we ran system-info. data.latest() always reads the most recent version. Older versions stay available until garbage collection removes them.

What we built

We created two behaviors, connected them with a data.latest() expression so one reads the other's output, ran them through a workflow, and explored the data they produced — listing artifacts, reading content, querying across behaviors with CEL predicates, and inspecting version history.