Semi-structured: a [*] path mapped to a to-many property returns a stringified array instead of a collection

[rafaelbey]

What happens

A [*] path mapped to a to-many primitive property returns one row holding the array's text, rather than a collection.

Class wild::Row
{
  id: Integer[1];
  names: String[*];
}

names: extractFromSemiStructured([wild::store::DB]T.DOC, 'divisions[*].name', 'VARCHAR[]')

Against {"divisions":[{"name":"Alpha"},{"name":"Beta"}]}:

query	result
project(~[id, v: r | $r.names])	one row, "[\"Alpha\",\"Beta\"]"
project(~[id, v: r | $r.names->joinStrings(',')])	one row, "[Alpha, Beta]"

Expected: two rows, Alpha and Beta.

Why it matters

No error is raised at compile or run time. A modeller declares String[*], sees an array-shaped value in a spot check, and ships a property that is actually a single string. The rendering differs depending on how the property is queried, which makes it easier still to mistake for a working collection.

Why it happens

Multiplicity in a relational mapping comes from row cardinality. explodeSemiStructured produces rows, so a to-many through a join works normally — meta::relational::tests::semistructured::nested::testNestedExplode maps teams: Team[*] that way and returns one row per (division, team) on DuckDB, Snowflake and Databricks.

A [*] path produces a value: one row with an array in one column. There are no rows for the to-many to range over, so the array is handed back as a single value.

What would be reasonable

Either of these would be an improvement over the current silence:

1. Reject it at compile time — a to-many property mapped to an array-valued expression is not expressible today, and saying so is better than a wrong answer.
2. Support it — fan the array out to rows, so [*] bound to a to-many property behaves the way a modeller reading the mapping would expect. This is the outcome that was expected when the gap was found.

Option 2 is the useful one; option 1 is worth having in the meantime, since the failure is currently invisible.

Where this came from

Found while adding [*] wildcard path support to the relational store language (#5097). The wildcard work itself is complete and tested — this is specifically about binding the result to a to-many property.

Reproduction is one property mapping; the models in legend-engine-xt-relationalStore-emit/src/test/resources/relational-emit-models/relational-semistructured-wildcard and core_relational/relational/tests/semistructured/model/wildcardPathInStoreLanguage.legend provide the surrounding setup.

[rafaelbey]

Assessment of option 1 (reject at compile time), from looking at where the check would live — recording it here rather than building it, so the next person doesn't have to re-derive it.

Where. HelperRelationalBuilder.processAbstractRelationalPropertyMapping, around the point the property is resolved onto the mapping. Both facts needed are in hand there: the resolved property, so its multiplicity, and the compiled RelationalOperationElement.

The rule. Property is to-many and the operation is definitely array-valued → raise.

The work is in "definitely". It has to be precise rather than conservative: flagging on unknown would reject every existing to-many mapped through a join. Two identifiable cases:

• extractFromSemiStructured(…, 'T[]') — the declared type says array
• an array-returning dyna function: array_filter, array_transform, array_flatten, array_sort, array_reverse, array_distinct, array_append, array_concatenate, array_slice, array_take, array_drop, array_init, array_tail

Deliberately excluded, because they return scalars: array_size, array_max, array_min, array_sum, array_to_string, array_first, array_last, array_position, array_contains. Getting that split wrong in the other direction would reject mappings that work today — array_to_string over a wildcard is the common, correct shape.

Risk. Low. Existing to-many properties map through joins, which are a different node, so they cannot trip the check; a false positive would surface immediately as compile failures across the model suites.

One caveat on rollout. This turns models that compile today into compile errors. That is the intent, but it is not the same as tightening an unknown dyna name — those already fail, so promoting them cannot break anything that works. Here the case currently succeeds, which is the situation docs/engineering/architecture/relational-dynafunctions.md §10.4 says should warn before it errors.

Option 2 (fan out to rows) remains the outcome worth having; this is only about closing the silent window in the meantime.