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.

#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."