collect_spec

Relational functions collect_spec

syntax

• collect_spec(spec, tree_item, selection domain unit, org_rel or condition)

definition

collect_spec(spec, ...) collects the subitems of tree_item onto the selection domain unit, configured by the spec argument instead of by the function name. It is the collect_attr_by_org_rel / collect_attr_by_cond pair with its choices made explicit, plus the collection scopes that have no named form.

The spec is a string of ;-separated words; order does not matter.

word	meaning
by_org_rel	the 4th argument is an org_rel relation, used in a lookup
by_cond	the 4th argument is a condition, used in a collect_by_cond
ref	also collect through the referred-item chain
sub	also collect from sub-containers, mirroring them in the result

One of by_org_rel / by_cond is required: the last argument is read as one or the other, and guessing would silently produce a different result. An unknown word is reported where the item is defined.

Collection is intrinsically catch-all: every matching item in the requested scope becomes an update dependency. ref and especially sub broaden that scan, so use them only when those extra dependencies are intended and cannot create a recursion.

Since GeoDMS 20.18.0, the collector excludes a source attribute whose calculation is downstream from the item that holds the collect_spec call. This prevents a generated result from trying to collect an attribute that refers back to that result. The same rule applies to collect_attr_by_org_rel and collect_attr_by_cond. Earlier versions tried to collect such attributes and could report an invalid recursion. A warning identifies each excluded attribute.

equivalences

named function	collect_spec
collect_attr_by_org_rel	collect_spec('by_org_rel', C, dom, org_rel)
collect_attr_by_cond	collect_spec('by_cond', C, dom, cond)

Prefer the named function when one exists; reach for collect_spec when you need ref or sub.

example

unit<uint32> Stops := Network/Stops;          // a reference: no sub-items of its own

container attrs := collect_spec('by_org_rel;ref', Stops, Selection, Selection/org_rel);

Without ref, Stops has nothing to collect and the call only warns. ref reaches the attributes of Network/Stops through the reference — the same chain that makes Stops/name resolve.

With by_cond the last argument is a condition on the source domain instead, exactly as collect_attr_by_cond takes it:

container attrs := collect_spec('by_cond', City, ZHCities, City/RegionCode == 200);

sub

sub mirrors a sub-container into the collected result. For a City that keeps its coordinates in a sub-container:

unit<uint32> City
{
   attribute<string> name;
   container geo { attribute<point_rd> point (City); }
}

container attrs := collect_spec('by_org_rel;sub', City, ZHCities, ZHCities/org_rel);

gives attrs/name and attrs/geo/point. Note that an attribute in a sub-container needs its domain unit spelled out — it is not a direct sub-item of the unit, so there is nothing to infer it from.

ref and sub mean exactly what they mean for select_spec; see that page for the shadowing rule and for the scopes in full.

applies to

• spec a parameter of value type string; usually a literal
• tree_item can be any tree item, but usually a unit or container
• selection domain unit a unit with a value type of the group CanbeDomainUnit
• org_rel a relation from the selection domain unit toward the domain of the collected attributes; condition a boolean attribute on that domain

since version

20.17.0

see also

• select_spec
• collect_attr_by_org_rel
• collect_attr_by_cond