table_spec

syntax

table_spec(spec, tree_item, selection domain unit D, org_rel or condition) -> unit<D>

definition

table_spec(spec, …) returns a new Domain unit based on the supplied selection domain unit, with matching subitems of tree_item collected directly beneath the returned unit. It is the table-producing counterpart of collect_spec: collect_spec returns only a container of collected attributes, whereas table_spec returns the selection domain itself as a table.

The supplied selection domain is not modified. The result is a fresh unit that refers to it, so the original unit can safely be shared by other calculations.

With by_org_rel, the supplied fourth argument is also materialized directly as the result’s org_rel. The table therefore exposes the exact relation used for collection as an own subitem, also when the returned unit refers to a separately calculated selection domain.

The spec uses the same ;-separated words as collect_spec:

word	meaning
`by_org_rel`	the fourth argument is an org_rel used to look up the source attributes
`by_cond`	the fourth argument is a condition used by collect_by_cond
`ref`	also collect through the referred-item chain
`sub`	also collect from sub-containers, mirroring them in the result

Exactly as for collect_spec, one of by_org_rel / by_cond is required.

Like other generating meta-functions (select_spec, collect_spec, and the for_each family), table_spec must be the whole calculation rule. It cannot be used as a sub-expression. A function may return table_spec(...), provided that call is the whole reduced function result.

table_spec is a catch-all collector: every matching item in the requested scope becomes an attribute and an update dependency of the result. ref and especially sub broaden that scope, so use them only when the additional 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 table_spec call. This prevents the generated table from trying to collect an attribute that refers back to that table. Earlier versions tried to collect such attributes and could report an invalid recursion. A warning identifies each excluded attribute.

example

unit<uint32> Selection := select_with_org_rel(City/RegionCode == 200);

unit<uint32> ZHCities := table_spec(
    'by_org_rel;sub',
    City,
    Selection,
    Selection/org_rel
);

ZHCities has the same rows as Selection, while matching attributes from City are generated directly as ZHCities/name, ZHCities/RegionCode, and—for example—ZHCities/geo/point. ZHCities/org_rel is the relation supplied as the fourth argument.

applies to

spec a string parameter, normally a literal
tree_item any tree item, normally a unit or container
selection domain unit a domain unit
org_rel a relation from that selection domain to the source-attribute domain, or condition a boolean attribute on the source domain

since version

20.18.0