table_spec

Relational functions 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.

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

see also

• collect_spec
• select_spec
• Index