Docs · Concepts

Parameters

One named value shared by every source in a Check — types, pick lists, moving dates and multi-value lists.

A parameter is one named value defined on a Check and referenced as {{name}} from any of its data sources. It is the Check-scoped counterpart of an environment variable.

Typical use: a business date, a store code, a currency, a flag that switches a query between two shapes.

#The four types

A number whose value is not actually numeric falls back to being quoted. Interpolating unvalidated text into a statement unquoted would let a parameter value change the shape of the query.

#Writing the reference

In a query you may write {{name}} bare or already quoted — both produce the same statement. So this:

WHERE store_code = {{store}}

and this:

WHERE store_code = '{{store}}'

are equivalent. You do not have to remember which convention this parameter uses.

Names may contain letters, digits, dot, dash or underscore. Nothing else resolves.

#Dates

Three output formats: YYYY-MM-DD, YYYYMMDD, or full ISO. You choose which, because the system on the other end has an opinion.

Input is accepted as YYYY-MM-DD, YYYYMMDD or DD/MM/YYYY. Dates are never constructed by handing a string to a date parser, precisely so that a timezone cannot shift the day.

Moving dates are the useful part. Instead of a fixed value, a date parameter can hold an expression — TODAY, YESTERDAY, TODAY-1, START_OF_MONTH-1 — worked out afresh at every run. A nightly Check reconciling yesterday needs no maintenance.

#Empty

By default a missing number or date fails the run, and the editor warns you in advance: "A run will fail: this parameter …".

Number and date parameters can opt into Empty instead: "Empty is a value: a run does not fail for the missing number, and SQL receives NULL. A run can still supply one."

#Pick lists

Bind a parameter to a list and it is chosen from a menu instead of typed — shown by name, sent as a code.

That split is the point. Nobody remembers that Madrid Serrano is store 1710104, and no query accepts "W-MADRID SERRANO". The list shows one and substitutes the other.

Three sources for the list, mutually exclusive:

From a collection attached to a data source. Choosing an entry supplies the value and narrows the run to that site.

From a library collection, read directly. This is the only way to pick from a list of plain values.

From Business Locations. Every open place with a code becomes a choice, shown as a tree.

With the Business Locations binding you can narrow what the reader is offered — by rung, by type, by what sits under a given place, or by which system plays a given role there. You also choose what a choice sends: the place itself and everything under it, or the codes at a named rung beneath it. That is what lets somebody choose a country and have the run cover its stores.

The places a list offers, and any value of the parameter, can also be written as a place query rather than picked: $Fascia = Outlet AND $Country = France. It stays a query, and each run reads the estate as it is that day, so the outlet that opens next month is in it without anybody ticking it. The box suggests names and values, counts the stores a query keeps, and says why when it keeps none. See Choosing places by what they are.

A list bound to Business Locations also narrows the run to the machines its choice reaches, so choosing France runs a fanned-out source on the French stores' hosts only.

#Several values

Several values is a flag on a parameter rather than a fifth type, and deliberately so: a list of store codes is a list of numbers, a list of business dates is a list of dates, and each item still has to be rendered as its type — or the same IN clause that works for text breaks for dates.

Both spellings work:

WHERE store_code IN {{stores}}
WHERE store_code IN ({{stores}})

The first gains its parentheses; the second does not get a second pair.

For a REST source, you choose how several values reach the query string: comma-joined, the key repeated, bracketed, or a JSON array.

#Overrides

A parameter can be overridden for this run without being saved: "Applies to the next run of any source or aggregation in this check. Not saved." The override is recorded on the run, so you can see what a past result was actually asked for.

#Recode

Some systems have their own word for a value everything else already has a word for — a bucket called ON_HAND everywhere and 01A in one place.

Recode for a data source gives that one source its own translation table. What reaches its query is translated, in that query alone, and nothing else in the Check has to know.

#Parameters in the library

A library data source declares what it asks a Check for — the type, the default and the list. Every Check that adds it starts from those, and is told: ""Daily sales — POS" added, with 2 parameter(s) it needs."