Change one value without touching the YAML
Declare one typed output-file parameter, override it at run time, and prove that the same job writes to the requested scope.
1. Objective
Goal
Add parameters.yaml, replace the destination filename with Hydra's documented {{ param:output_file }} placeholder, and run the job with -P output_file=scoped-output.csv.
Keep working from the cli-course folder. The job is named first-job, and the workflow lessons add workflow.yaml beside it; every command and terminal excerpt in this lesson was run against that same cumulative project.
Reading a result. Durations and process identifiers vary between machines — ignore them. What proves a run is the stable evidence: named files, resolved identifiers, row counters, step states, HTTP status. If one of those differs from the lesson, fix the previous step before continuing.
Prerequisites
- Lesson 6 completed and checked.
- The validated
first-jobCSV project. - A terminal opened in the
cli-coursefolder.
2. Steps
01Declare the parameter
Objective
Give output_file a type, default, and description.
Actions
- Create
first-job/parameters.yaml. - Add the
parametersmapping exactly as shown. - Keep the default equal to the file used in earlier lessons.
parameters:
output_file:
type: string
default: output.csv
description: Output CSV file name
The declaration preserves the earlier behavior when no override is passed.
parameters:
output_file:
type: string
default: output.csv
description: Output CSV file name02Use the parameter in the destination
Objective
Resolve the destination filename while retaining the job-relative data folder.
Actions
- Open
first-job/destinations.yaml. - Replace only
load.table. - Use the colon form of Hydra's parameter placeholder.
load:
table: "data/{{ param:output_file }}"
mode: replace
The destination path combines a stable folder with a runtime-resolved filename.
table: "data/{{ param:output_file }}"03Override the filename
Objective
Run the unchanged pipeline with a one-command output scope.
Actions
- Pass one
KEY=VALUEpair with-P. - Use a filename without path traversal so output remains under
data.
hdrctl run first-job -P output_file=scoped-output.csv
The actual run succeeds with the same observed row counts.
✅ Pipeline completed successfully in 3.2s Rows read : 3 Rows written: 2
04Read the parameterized output
Objective
Prove that the override selected a new destination file.
Actions
- Open
first-job/data/scoped-output.csv. - Compare the rows with the default output from lesson 5.
Get-Content first-job\data\scoped-output.csv
The requested file exists and contains the two filtered rows.
id,name,value 1,Alice,100.0 2,Bob,200.0
3. Checklist
| Verification | Expected result |
|---|---|
| Parameter declaration | output_file is a string with default output.csv |
| Placeholder grammar | Uses {{ param:output_file }} |
| Run result | Reads 3 and writes 2 rows |
| Override evidence | scoped-output.csv contains Alice and Bob |
4. Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Parameter is unresolved | The placeholder spelling differs from the declaration | Use the same output_file key in both files |
| CLI rejects the argument | The pair has no equals sign | Pass -P output_file=scoped-output.csv |
| The default file is written | The override was omitted or placed after a shell parsing error | Copy the exact command and keep the value unquoted unless it contains spaces |
5. Next lesson
The job can now change its output scope without manifest edits. The next lesson inventories the containing project with hdrctl list and reads what that structural scan does—and does not—prove.