Docs: clarify CONCAT_WS behavior with absent/partial input values

[mitselek]

Summary

The Formulas docs describe CONCAT_WS as "Joins values with a separator — the last value is used as the separator" and add that "When no values resolve... most functions return undefined." But the partial-resolution case — when some inputs are absent and others present — isn't documented. This case is the most useful one in practice (it's how you express coalesce/fallback patterns that the formula DSL otherwise can't), and the actual behavior is better than the docs suggest. Worth spelling out so users can confidently rely on it.

What I tested

Created a temporary entity type with three properties:

• a — string
• b — string
• combined — formula: a b ' / ' CONCAT_WS

Then four instances with different combinations of a and b. Read back the formula's stored value.

a	b	combined
"A"	"B"	"A / B"
"A"	absent	"A"
absent	"B"	"B"
absent	absent	"" (empty string)

Useful findings (please document)

1. Absent values are skipped cleanly. When one input is present and another absent, CONCAT_WS returns only the present value — no stray separator. This makes it a usable fallback / coalesce pattern. Example: value_a value_b ' / ' CONCAT_WS returns value_a when value_b is absent.
2. Both-absent case returns empty string, not undefined. Slightly different from the "most functions return undefined" statement in the docs. The combined property gets written with value "" in this case (the property exists, with empty string value). Whether that's intentional or a minor inconsistency with MIN/MAX/AVERAGE is unclear — but it's worth being explicit either way.

Suggested docs change

Under Formulas → Empty Input Behaviour, add a row for CONCAT_WS and clarify the partial-resolution case:

| Function   | Empty-input result | Partial-input behaviour |
|------------|--------------------|--------------------------|
| CONCAT     | undefined           | concatenates resolved values |
| CONCAT_WS  | "" (empty string)   | joins resolved values, skips absent ones (no stray separators) |

Or add a dedicated "Coalesce / fallback patterns" subsection showing the idiom — it's a non-obvious but very useful capability.

Why this matters in practice

We're using this for property inheritance in Polyphony's Entu schema — editions can override their parent work's voicing / duration / language, with a *_display formula that shows either the edition's own value (if set) or the work's value (if not), or both side-by-side when they diverge:

voicing _parent.work.original_voicing ' / ' CONCAT_WS

This wouldn't be safe to rely on without the empirical confirmation above — the docs leave the behavior ambiguous enough that I had to live-probe before committing to it.

[mitselek]

Follow-up: list-valued inputs

Ran a parallel probe with list: true properties to confirm the multi-value case (relevant since real-world inheritance often involves list-typed properties like languages, voicings, genres).

Setup

Same entity type with three properties, but a and b both have list: true:

• a — string, list
• b — string, list
• combined — formula a b ' / ' CONCAT_WS

Results

a	b	combined
["A1","A2"]	["B1","B2"]	"A1 / A2 / B1 / B2"
["A1","A2"]	[]	"A1 / A2"
[]	["B1","B2"]	"B1 / B2"
["A1","A2"]	["B1"]	"A1 / A2 / B1"
["A1"]	["B1"]	"A1 / B1"
[]	[]	""

Useful findings (please document)

1. List values are flattened in posting order. All values from input a come first, then all values from b, all joined with the separator. The ordering preserves whatever order the property values were POSTed in.
2. Mixed-cardinality is handled symmetrically — partial absence is treated like a shorter list. No stray separators.
3. The empty-list case behaves identically to absent — [] is indistinguishable from "not set" in the formula's output.

Suggested docs change (extending the previous comment)

Under Formulas → Empty Input Behaviour or in a new "List-valued inputs" subsection:

When a formula references a list: true property, all of the property's values are treated as a sequence. Functions that combine multiple inputs (e.g. CONCAT_WS, SUM, COUNT, AVERAGE) operate on the flattened concatenation of all referenced inputs' values, in the order: each input's values left-to-right, then inputs left-to-right.

This is the obvious and useful behavior — worth being explicit so users don't fear that list-valued properties will misbehave inside formulas.

[mitselek]

Follow-up #2: CONCAT_WS does NOT deduplicate

Third probe to round out the picture. Question: when the same value appears multiple times (within an input's list, or across two inputs), does CONCAT_WS collapse duplicates?

Results

a	b	combined
["X"]	["X"]	"X / X"
["X","Y"]	["Y","Z"]	"X / Y / Y / Z"
["X","Y"]	["X","Y"]	"X / Y / X / Y"
["X","X"]	["Y"]	"X / X / Y"
["SATB"]	["SATB"]	"SATB / SATB"
["en","et"]	["la","en"]	"en / et / la / en"

Useful finding

No deduplication — values are joined verbatim, in input order, including within-list and across-input duplicates. This is consistent behavior (no special-cases for duplicates), but it's a real limitation for fallback/coalesce patterns.

Impact on the use case I described earlier

The "value-with-fallback" pattern I described in the original comment — using voicing _parent.work.original_voicing ' / ' CONCAT_WS to show "edition's voicing if set, else work's, with both if they differ" — only works cleanly when the edition's value differs from the work's. The common case (edition matches the original composition) produces "SATB / SATB" instead of a clean "SATB".

This means the formula pattern requires a strict cataloging convention ("leave the edition's value empty when it matches the work; only set it when it diverges") that the schema can't enforce.

Suggested doc / capability note

In addition to documenting the no-dedup behavior, this exposes a gap: there's no formula function that expresses coalesce / "first non-empty value" semantics. The list of available functions is CONCAT, CONCAT_WS, COUNT, SUM, SUBTRACT, MULTIPLY, DIVIDE, AVERAGE, MIN, MAX, ABS, ROUND. None of these — and no combination of them — lets you express "use a if it has a value, otherwise use b".

That's a real use case (property inheritance / fallback display), and currently the only workaround is application-layer logic outside Entu. A COALESCE (or FIRST) function — return the first input that has a resolved value, skip the rest — would unlock the pattern. Filed as a thought rather than a hard request; up to the Entu team whether it fits the formula DSL's philosophy.