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 loginYour 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 noneYou 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-infoCreated: 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 executeYou 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-infoData 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 summariserOpen 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-pipelineCreated: info-pipeline
Path: .../workflows/workflow-info-pipeline.yamlOpen 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: executeNotice 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-pipelineValidating: 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: PASSEDNow 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-pipelineData 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 resultsThe 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 resultYou 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.