dirigent-examples 0.15.0__py3-none-any.whl

dirigent_examples/shelves/recipes/http-timeout-override.yaml

@@ -0,0 +1,104 @@
+# Three deadlines sit around one HTTP call. Know which one you are setting.
+#
+# In:  a delay in seconds, as a parameter, defaulting to 2.
+# Out: a slow call that completes inside its own timeout, and its measured duration.
+#
+# The three, from the inside out:
+#
+#   timeout on the step's config             how long this one call may take before the
+#                                            client gives up. It overrides the connection's
+#                                            timeout for this call and nothing else.
+#   timeout on the connection                the default for every call made through it,
+#                                            which is where a slow API's whole profile
+#                                            belongs rather than in each step.
+#   timeout on the step                      the engine's deadline on the attempt, which
+#                                            covers the block's entire execution, retries of
+#                                            an inner operation included. It is step-level
+#                                            engine semantics, uniform across every block,
+#                                            and it is what kills a step that hangs somewhere
+#                                            the HTTP client is not.
+#
+# The inner one is the one to reach for when a single endpoint is slow: a report that takes
+# forty seconds to build does not justify raising the deadline on every call to that host,
+# and a health check that should answer in one second is a step-level override in the other
+# direction.
+#
+# https://postman-echo.com/delay/<seconds> answers after the seconds it is given, so the
+# relationship is visible: with the default the call takes about 2s against a 10s budget and
+# the run is green. Setting -p delay=6 against -p timeout=3 fails the step instead, as a
+# timeout rather than as an error the server returned, which is a different failure class
+# and retried differently.
+#
+# The engine's own step timeout is set here too, comfortably above the call's, so that a
+# hang outside the HTTP client -- a name that never resolves, a socket that never closes --
+# still ends the attempt.
+#
+# To change it: -p delay=6 -p timeout=3 to see the failure, or -p delay=1 for a fast run.
+#
+#   dg run --local examples/recipes/http-timeout-override.yaml
+#   dg run --local examples/recipes/http-timeout-override.yaml -p delay=6 -p timeout=3   # fails, on purpose
+
+format: dirigent/v1
+kind: pipeline
+code: http-timeout-override
+name: A per-call timeout override
+description: Override a connection's timeout for one slow call, under an engine step deadline that covers the whole attempt.
+
+tags: [recipes, http, transform]
+
+requires:
+  blocks:
+    - http.request
+    - transform.jq
+
+connections:
+  echo-slow:
+    kind: http
+    config:
+      base_url: https://postman-echo.com
+      # The default for every call through this connection. Deliberately short, so the
+      # override below is doing real work.
+      timeout: 3s
+      health_path: /get
+
+params:
+  type: object
+  properties:
+    delay:
+      type: integer
+      minimum: 0
+      maximum: 10
+      default: 2
+      description: How many seconds the endpoint waits before answering.
+    timeout:
+      type: number
+      default: 10
+      description: This call's own deadline, overriding the connection's 3 seconds.
+
+steps:
+  slow:
+    block: http.request
+    # The engine's deadline on the whole attempt, well above the call's own, so a hang
+    # outside the HTTP client still ends the step.
+    timeout: 60s
+    config:
+      connection: echo-slow
+      path: /delay/${params.delay}
+      method: GET
+      # This call alone; every other call through echo-slow keeps the 3 second default.
+      timeout: ${params.timeout}
+
+  timing:
+    block: transform.jq
+    depends_on: [slow]
+    config:
+      input:
+        status: ${steps.slow.output.status}
+        duration_ms: ${steps.slow.output.duration_ms}
+        budget: ${params.timeout}
+      program: |
+        {status, duration_ms,
+         budget_ms: (.budget * 1000),
+         # A call that lands close to its budget is a call about to start failing
+         # intermittently, which is worth reporting before it does.
+         headroom_ms: ((.budget * 1000) - .duration_ms)}

dirigent_examples/shelves/recipes/jq-dedupe-by-key.yaml

@@ -0,0 +1,78 @@
+# Reduce a list with repeated keys to one row per key, and say which row won.
+#
+# In:  readings where the same station reports several times, out of order, some of them
+#      corrections of an earlier one.
+# Out: {first_seen, last_seen, latest, duplicates} -- three different answers to "dedupe",
+#      side by side, plus the keys that had more than one row.
+#
+# Dedupe is never one operation, because "the duplicate" is not a property of the data; it
+# is a decision about which row to keep:
+#
+#   unique_by(.station)          keeps the smallest row by the whole key order, which for a
+#                                sorted-by-nothing input is arbitrary and only safe when the
+#                                duplicates are genuinely identical.
+#   group_by then .[0] / .[-1]   keeps the first or last row of each bucket in input order,
+#                                which is the answer when arrival order carries meaning.
+#   group_by then max_by(.at)    keeps the newest row by a timestamp the data carries, which
+#                                is the only one of the three that survives a reorder.
+#
+# The last is almost always the right one for corrections, and this recipe reports the other
+# two beside it so the difference is visible in the output rather than argued about.
+#
+# duplicates is computed before anything is thrown away: a dedupe that reports nothing is a
+# dedupe nobody can audit.
+#
+# To change it: -p key=region dedupes on a different column; the timestamp column stays .at.
+#
+#   dg run --local examples/recipes/jq-dedupe-by-key.yaml
+#   dg run --local examples/recipes/jq-dedupe-by-key.yaml -p key=region
+
+format: dirigent/v1
+kind: pipeline
+code: jq-dedupe-by-key
+name: Dedupe by key, three ways
+description: Collapse repeated rows to one per key by first seen, last seen, and newest timestamp, and list the keys that repeated.
+
+tags: [recipes, transform, jq]
+
+requires:
+  blocks:
+    - value.const
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    key:
+      type: string
+      default: station
+      description: The column a row is deduplicated on.
+
+steps:
+  rows:
+    block: value.const
+    config:
+      value:
+        - { station: st-1, region: east, at: "2026-01-01T06:00:00Z", celsius: 4 }
+        - { station: st-2, region: west, at: "2026-01-01T06:00:00Z", celsius: -1 }
+        # A correction: same station, later timestamp, arriving before the row it corrects.
+        - { station: st-1, region: east, at: "2026-01-01T09:00:00Z", celsius: 5 }
+        - { station: st-1, region: east, at: "2026-01-01T07:00:00Z", celsius: 40 }
+        - { station: st-3, region: east, at: "2026-01-01T06:00:00Z", celsius: 7 }
+
+  deduped:
+    block: transform.jq
+    depends_on: [rows]
+    config:
+      input:
+        key: ${params.key}
+        rows: ${steps.rows.output.value}
+      program: |
+        . as {$key, $rows}
+        | ($rows | group_by(.[$key])) as $buckets
+        | {first_seen: [$buckets[] | .[0]],
+           last_seen: [$buckets[] | .[-1]],
+           # max_by reads the timestamp the row carries, so a late arrival cannot win by
+           # arriving late and an early correction cannot lose by arriving early.
+           latest: [$buckets[] | max_by(.at)],
+           duplicates: [$buckets[] | select(length > 1) | {key: .[0][$key], rows: length}]}

dirigent_examples/shelves/recipes/jq-defaults-and-nulls.yaml

@@ -0,0 +1,91 @@
+# Absent, null, false, and empty string are four different things. Handle each on purpose.
+#
+# In:  rows where a field is missing entirely, present and null, present and false, and
+#      present and empty -- one row for each case.
+# Out: {naive, careful, report} -- the same defaulting written the wrong way and the right
+#      way, with a per-row report of which case each field actually was.
+#
+# // is the alternative operator, and it answers with its right side when the left is null
+# OR false. That second half is the trap: .enabled // true can never answer false, so a row
+# that switched a feature off comes back on. The naive object in the output is that bug,
+# left in on purpose so the careful one below has something to be different from.
+#
+# The three questions that are actually being asked are different questions, and jq spells
+# each of them:
+#
+#   has("enabled")        is the key present at all -- absent and null are distinguished.
+#   .enabled == null      is the value the null value, whether or not the key is there.
+#   (.count // 0)         is it null-or-false, which for a number is a fine default.
+#
+# For a boolean, the safe defaulting is `if has("x") and .x != null then .x else DEFAULT end`.
+# For a string, "" is a value and // will not replace it, so an empty-means-absent rule is
+# written out rather than assumed.
+#
+# tonumber on a string that is not a number is an error rather than a null, so it goes
+# through try/catch. That is the one place a reshape may decide, because the alternative --
+# a failed step -- reports a bad cell as an outage.
+#
+# To change it: -p strict_numbers=true makes an unparsable count null instead of zero, which
+# is what a load that must not invent a measurement wants.
+#
+#   dg run --local examples/recipes/jq-defaults-and-nulls.yaml
+#   dg run --local examples/recipes/jq-defaults-and-nulls.yaml -p strict_numbers=true
+
+format: dirigent/v1
+kind: pipeline
+code: jq-defaults-and-nulls
+name: Defaults, nulls, and the // trap
+description: Distinguish absent, null, false, and empty when defaulting fields, and show what the alternative operator gets wrong.
+
+tags: [recipes, transform, jq]
+
+requires:
+  blocks:
+    - value.const
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    strict_numbers:
+      type: boolean
+      default: false
+      description: Leave an unparsable count null rather than defaulting it to zero.
+
+steps:
+  rows:
+    block: value.const
+    config:
+      value:
+        - { id: a, enabled: true, count: "3", label: Harbour }
+        # enabled is absent: nothing was said about it.
+        - { id: b, count: "0", label: Ridge }
+        # enabled is null: something was said, and it said nothing.
+        - { id: c, enabled: null, count: null, label: "" }
+        # enabled is false: something was said, and it said no. This is the row // ruins.
+        - { id: d, enabled: false, count: "not a number", label: Delta }
+
+  defaults:
+    block: transform.jq
+    depends_on: [rows]
+    config:
+      input:
+        rows: ${steps.rows.output.value}
+        strict: ${params.strict_numbers}
+      program: |
+        . as {$rows, $strict}
+        | {naive: [$rows[] | {id, enabled: (.enabled // true)}],
+           careful: [$rows[]
+             | {id,
+                enabled: (if has("enabled") and .enabled != null then .enabled else true end),
+                count: (if .count == null then (if $strict then null else 0 end)
+                        else (try (.count | tonumber)
+                              catch (if $strict then null else 0 end)) end),
+                # An empty string is a value, so // never sees it; the rule is written out.
+                label: (if (.label // "") == "" then "unnamed" else .label end)}],
+           report: [$rows[]
+             | {id,
+                enabled_case: (if has("enabled") | not then "absent"
+                               elif .enabled == null then "null"
+                               elif .enabled == false then "false"
+                               else "true" end)}]}

dirigent_examples/shelves/recipes/jq-group-by-and-sum.yaml

@@ -0,0 +1,74 @@
+# Total a numeric column per group, and keep the grand total beside the groups.
+#
+# In:  a flat list of sales rows -- {region, product, units, revenue}.
+# Out: {as_of, groups: [{region, rows, units, revenue, mean_revenue}], total: {...}}.
+#
+# group_by sorts by the key and buckets, so every bucket is a list and the group's key is
+# read back off any element of it -- .[0].region. Everything after that is ordinary list
+# arithmetic: add over a mapped column, length for the count, and a division that is safe
+# because group_by never produces an empty bucket.
+#
+# The grand total is computed from the rows rather than from the groups, because summing
+# already-rounded group totals is how a report stops adding up.
+#
+# To change it: -p group_by=product buckets the same rows the other way. The program reads
+# the key with .[$key], jq's dynamic field access, which is what lets the column be a
+# parameter instead of a second program.
+#
+#   dg run --local examples/recipes/jq-group-by-and-sum.yaml
+#   dg run --local examples/recipes/jq-group-by-and-sum.yaml -p group_by=product
+
+format: dirigent/v1
+kind: pipeline
+code: jq-group-by-and-sum
+name: Group and sum with jq
+description: Bucket flat rows by one column, total two numeric columns per bucket, and keep a grand total beside them.
+
+tags: [recipes, transform, jq]
+
+requires:
+  blocks:
+    - value.const
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    group_by:
+      type: string
+      default: region
+      description: The column the rows are bucketed by.
+
+steps:
+  rows:
+    block: value.const
+    config:
+      value:
+        - { region: east, product: pump, units: 3, revenue: 300 }
+        - { region: east, product: valve, units: 10, revenue: 250 }
+        - { region: west, product: pump, units: 1, revenue: 100 }
+        - { region: west, product: valve, units: 4, revenue: 100 }
+        - { region: north, product: pump, units: 2, revenue: 200 }
+
+  totals:
+    block: transform.jq
+    depends_on: [rows]
+    config:
+      # The key travels as data beside the rows rather than spliced into the program text:
+      # a program carrying a ${...} cannot be compiled when the document is applied.
+      input:
+        key: ${params.group_by}
+        rows: ${steps.rows.output.value}
+      program: |
+        . as {$key, $rows}
+        | {as_of: "2026-01-01",
+           groups: ($rows
+             | group_by(.[$key])
+             | map({group: .[0][$key],
+                    rows: length,
+                    units: (map(.units) | add),
+                    revenue: (map(.revenue) | add),
+                    mean_revenue: ((map(.revenue) | add) / length)})),
+           total: {rows: ($rows | length),
+                   units: ($rows | map(.units) | add),
+                   revenue: ($rows | map(.revenue) | add)}}

dirigent_examples/shelves/recipes/jq-join-two-lists.yaml

@@ -0,0 +1,77 @@
+# Join two lists on a key, keeping the rows that match nothing.
+#
+# In:  a list of stations (the dimension) and a list of readings (the facts).
+# Out: {joined: [...], unmatched: [...]} -- every reading enriched, and the ones whose
+#      station is in no dimension row listed separately rather than silently dropped.
+#
+# A jq program has exactly one input, so a join composes its two sides into one object in
+# the step's config and destructures them apart again in the program. INDEX builds the
+# lookup table in one pass -- an object keyed by station id -- which turns the join from a
+# scan per reading into a lookup per reading.
+#
+# Both halves of the result come out of that one index: $by_id[.station] is null for a
+# reading nothing matched, so // supplies the default on the joined side and select collects
+# exactly those rows on the unmatched side. An inner join alone would report four readings
+# where five arrived, and never say which one went missing.
+#
+# To change it: index the other side to change the join's direction -- indexing the readings
+# and iterating the stations answers "which stations reported at all".
+#
+#   dg run --local examples/recipes/jq-join-two-lists.yaml
+#   dg run --local examples/recipes/jq-join-two-lists.yaml -p default_name=none
+
+format: dirigent/v1
+kind: pipeline
+code: jq-join-two-lists
+name: Join two lists with INDEX
+description: Join readings to their station dimension with INDEX, keeping the unmatched rows in a list of their own.
+
+tags: [recipes, transform, jq]
+
+requires:
+  blocks:
+    - value.const
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    default_name:
+      type: string
+      default: unknown station
+      description: The name a reading gets when its station is in no dimension row.
+
+steps:
+  stations:
+    block: value.const
+    config:
+      value:
+        - { id: st-1, name: Harbour, region: east }
+        - { id: st-2, name: Ridge, region: west }
+        - { id: st-3, name: Delta, region: east }
+
+  readings:
+    block: value.const
+    config:
+      value:
+        - { station: st-1, celsius: 4 }
+        - { station: st-2, celsius: -1 }
+        - { station: st-3, celsius: 7 }
+        # No st-9 in the dimension: this is the row the recipe exists for.
+        - { station: st-9, celsius: 2 }
+
+  join:
+    block: transform.jq
+    depends_on: [stations, readings]
+    config:
+      input:
+        stations: ${steps.stations.output.value}
+        readings: ${steps.readings.output.value}
+        fallback: ${params.default_name}
+      program: |
+        . as {$stations, $readings, $fallback}
+        | ($stations | INDEX(.id)) as $by_id
+        | {joined: [$readings[]
+             | . + {name: ($by_id[.station].name // $fallback),
+                    region: ($by_id[.station].region // null)}],
+           unmatched: [$readings[] | select($by_id[.station] == null) | .station]}

dirigent_examples/shelves/recipes/jq-long-to-wide.yaml

@@ -0,0 +1,76 @@
+# Turn long rows -- one record per measurement -- back into one wide row per subject.
+#
+# In:  [{station, date, measure, value}, ...].
+# Out: [{station, date, celsius, humidity, rainfall_mm}, ...], one row per station and date,
+#      with an explicit null in every cell the long form had no record for.
+#
+# This is jq-pivot-wide-to-long.yaml run backwards, and it is the harder direction, because
+# widening has to decide three things the melt never had to:
+#
+#   - What identifies a row. The key is composite here, so group_by takes a list and jq
+#     compares those lists element by element.
+#   - What the full set of columns is. It is collected from the whole input before the
+#     grouping, not from each group, or the rows come out ragged and something downstream
+#     has to reconcile them.
+#   - What a missing cell means. A blank object of nulls is merged under each group, so
+#     every output row carries every column whether that subject reported it or not.
+#
+# from_entries is the inverse of the melt's to_entries. Two records for the same measure in
+# one group would quietly leave the last one standing; catching that is a validate.schema
+# gate's job, never a reshape's.
+#
+# To change it: -p absent=n/a fills unreported cells with a marker instead of null, which is
+# what a csv reader that cannot tell an empty cell from a missing one wants.
+#
+#   dg run --local examples/recipes/jq-long-to-wide.yaml
+#   dg run --local examples/recipes/jq-long-to-wide.yaml -p absent=n/a
+
+format: dirigent/v1
+kind: pipeline
+code: jq-long-to-wide
+name: Pivot long rows to wide
+description: Widen one-record-per-measurement rows into one row per subject, with an explicit fill in every unreported cell.
+
+tags: [recipes, transform, jq]
+
+requires:
+  blocks:
+    - value.const
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    absent:
+      type: [string, "null"]
+      default: null
+      description: What fills a cell the long form carried no record for.
+
+steps:
+  long:
+    block: value.const
+    config:
+      value:
+        - { station: st-1, date: "2026-01-01", measure: celsius, value: 4 }
+        - { station: st-1, date: "2026-01-01", measure: humidity, value: 81 }
+        - { station: st-1, date: "2026-01-01", measure: rainfall_mm, value: 0 }
+        - { station: st-2, date: "2026-01-01", measure: celsius, value: -1 }
+        # st-2 reported no humidity that day: the wide row still gets the column.
+        - { station: st-2, date: "2026-01-01", measure: rainfall_mm, value: 3 }
+        - { station: st-1, date: "2026-01-02", measure: celsius, value: 6 }
+
+  wide:
+    block: transform.jq
+    depends_on: [long]
+    config:
+      input:
+        rows: ${steps.long.output.value}
+        absent: ${params.absent}
+      program: |
+        . as {$rows, $absent}
+        | ([$rows[].measure] | unique) as $columns
+        | ($columns | map({key: ., value: $absent}) | from_entries) as $blank
+        | [$rows
+           | group_by([.station, .date])[]
+           | {station: .[0].station, date: .[0].date}
+             + ($blank + (map({key: .measure, value: .value}) | from_entries))]

dirigent_examples/shelves/recipes/jq-nested-to-flat.yaml

@@ -0,0 +1,89 @@
+# Flatten deeply nested records into flat ones a csv or a parquet writer will accept.
+#
+# In:  records with nested objects and a list -- {id, site: {name, coords: {lat, lon}},
+#      tags: [...]}.
+# Out: flat records whose keys are the joined paths -- site.name, site.coords.lat, tags.
+#
+# Every row-oriented sink here refuses a nested value rather than writing it as text:
+# convert.std says so naming the row and the key, and convert.arrow says the same about a
+# parquet column. Flattening is therefore not a nicety before a csv, it is the step that
+# makes the csv possible at all.
+#
+# paths is the whole recipe. It emits the path to every leaf of a value, as an array of
+# keys, and getpath reads the value at one -- so join(".") is the single place that decides
+# what a flattened key looks like, and changing the separator is changing that one string.
+#
+# The predicate handed to paths is where a boolean column goes missing. paths(f) keeps a
+# path when f answers a truthy value, and for a cell holding false the tidy-looking
+# paths(scalars) answers false -- so the row silently loses the column. Writing the
+# predicate as a type comparison keeps it, and st-2's active: false in the output is the
+# proof.
+#
+# Lists are the case worth deciding rather than defaulting. paths walks into them too, which
+# would give tags.0 and tags.1 -- columns that move whenever an element is inserted. So the
+# list-valued fields are pulled out first and joined into one cell, by the step that knows
+# what the separator should be, and everything left flattens by path.
+#
+# To change it: -p separator=__ changes the joined key, which some warehouse loaders prefer
+# to a dot they would otherwise have to quote.
+#
+#   dg run --local examples/recipes/jq-nested-to-flat.yaml
+#   dg run --local examples/recipes/jq-nested-to-flat.yaml -p separator=__
+
+format: dirigent/v1
+kind: pipeline
+code: jq-nested-to-flat
+name: Flatten nested records
+description: Flatten nested records into joined-path keys, with list fields collapsed into one cell rather than indexed columns.
+
+tags: [recipes, transform, jq]
+
+requires:
+  blocks:
+    - value.const
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    separator:
+      type: string
+      default: "."
+      description: What joins the path segments of a flattened key.
+
+steps:
+  nested:
+    block: value.const
+    config:
+      value:
+        - id: st-1
+          site: { name: Harbour, coords: { lat: 59.91, lon: 10.75 } }
+          tags: [coastal, tidal]
+          active: true
+        - id: st-2
+          site: { name: Ridge, coords: { lat: 60.39, lon: 5.32 } }
+          tags: [alpine]
+          active: false
+
+  flat:
+    block: transform.jq
+    depends_on: [nested]
+    config:
+      input:
+        rows: ${steps.nested.output.value}
+        separator: ${params.separator}
+      program: |
+        . as {$rows, $separator}
+        | [$rows[]
+           # The list-valued fields are collapsed before the walk, so a new element never
+           # adds a column.
+           | (to_entries | map(select(.value | type == "array"))
+              | map({key: .key, value: (.value | join(","))}) | from_entries) as $lists
+           | (to_entries | map(select(.value | type != "array")) | from_entries) as $rest
+           # paths(f) keeps a path when f answers a truthy value, so paths(scalars) drops
+           # every leaf that is itself false. The predicate is written as a comparison so a
+           # false cell survives the flattening.
+           | ([$rest | paths(type | . != "object" and . != "array") as $p
+               | {key: ($p | join($separator)), value: getpath($p)}]
+              | from_entries)
+             + $lists]

dirigent_examples/shelves/recipes/jq-pivot-wide-to-long.yaml

@@ -0,0 +1,65 @@
+# Turn wide rows -- one column per measure -- into long rows, one record per measurement.
+#
+# In:  [{station, date, celsius, humidity, rainfall_mm}, ...], a column per measure.
+# Out: [{station, date, measure, value}, ...], one record per measure per row.
+#
+# Long is the shape almost every sink wants: a data value set, a tidy dataframe, a csv whose
+# header does not change when a new instrument is installed. The verb that gets there is
+# to_entries, which turns whatever is left of the object into {key, value} pairs once the
+# identifying columns have been removed with del. Naming the identifiers once, rather than
+# the measures, is what makes the program survive a new column.
+#
+# Dropping nulls is the decision worth seeing. A wide row carries a cell for a measure that
+# was never taken, and a long row for it would be a claim that a measurement of null
+# happened. select is where that claim is refused.
+#
+# To change it: -p keep_nulls=true emits a long row for every cell, which is what a sink
+# that distinguishes "not reported" from "not measured" wants.
+#
+#   dg run --local examples/recipes/jq-pivot-wide-to-long.yaml
+#   dg run --local examples/recipes/jq-pivot-wide-to-long.yaml -p keep_nulls=true
+
+format: dirigent/v1
+kind: pipeline
+code: jq-pivot-wide-to-long
+name: Pivot wide rows to long
+description: Melt a column-per-measure table into one record per measurement, dropping the cells that were never measured.
+
+tags: [recipes, transform, jq]
+
+requires:
+  blocks:
+    - value.const
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    keep_nulls:
+      type: boolean
+      default: false
+      description: Emit a long row for a measure that has no value, rather than dropping it.
+
+steps:
+  wide:
+    block: value.const
+    config:
+      value:
+        - { station: st-1, date: "2026-01-01", celsius: 4, humidity: 81, rainfall_mm: 0 }
+        - { station: st-2, date: "2026-01-01", celsius: -1, humidity: 74, rainfall_mm: null }
+        - { station: st-1, date: "2026-01-02", celsius: 6, humidity: null, rainfall_mm: 12 }
+
+  long:
+    block: transform.jq
+    depends_on: [wide]
+    config:
+      input:
+        rows: ${steps.wide.output.value}
+        keep_nulls: ${params.keep_nulls}
+      program: |
+        . as {$rows, $keep_nulls}
+        | [$rows[]
+           | . as $row
+           | (del(.station, .date) | to_entries[])
+           | select($keep_nulls or .value != null)
+           | {station: $row.station, date: $row.date, measure: .key, value: .value}]