Manipulating Tables and Lookup Tables

Overview

This page covers the functors and techniques used to read, iterate over, and restructure Tables and Lookup Tables once they exist. See Table Type and Lookup Table Type for the general format of these two types — column naming, key marking, and type inference — which this page assumes as background.

Tuple Type

A Tuple is a sequence of table cells, most often used to represent the key (or full set of keys) identifying a table row. Tuple elements are ordered by column index and have no names of their own — a Tuple by itself doesn't say which column each element belongs to; that mapping only exists in the context of the table it's being used against.

A single Real or String value connects directly to any port expecting a Tuple — Dinamica EGO converts it automatically, which is why a plain key value can be wired straight into a functor like Get Table Value without explicitly constructing a Tuple first. A multi-column key has to be built explicitly, one element at a time, by chaining Add Tuple Value calls — each call appends one value to the Tuple produced by the previous call:

// A single value auto-converts to a one-element Tuple; no AddTupleValue needed.
yearOnly := 2007;
// A composite key needs one AddTupleValue call per extra element: the first
// argument (2007) auto-converts to a one-element Tuple, and the call appends
// 4534272 to it, producing a two-element Tuple.
yearAndCity := AddTupleValue 2007 4534272;

Every functor below that identifies a row or sub-table by key takes that key as a Tuple.

Retrieving values and rows

GetTableValue

Reads a single cell.

Parameter	Type	Required?	Description
table	Table	Yes	The table to read from.
keys	Tuple	Yes	The key identifying the row.
column	name or index	Yes	Which value column to read. An index counts every column left to right, starting at 1, including key columns — so the first value column's index is one past the number of key columns, not 1 (see Table Type).
valueIfNotFound	matches the column	No	Returned instead of failing if the key isn't present.

Output: the value at that key and column.

GetTableRow

Reads every value column for one key at once.

Parameter	Type	Required?	Description
keys	Tuple	Yes	The key identifying the row.
table	Table	Yes	The table to read from.

Output: the row's value columns, as a Tuple — not the key columns, since those are already known from the keys input.

GetLookupTableValue

The Lookup Table equivalent of GetTableValue — no column argument, since a Lookup Table only ever has one.

Parameter	Type	Required?	Description
table	Lookup Table	Yes	The lookup table to read from.
key	Real	Yes	The key to look up.
valueIfNotFound	Real	No	Returned instead of failing if the key isn't present.

Output: the value for that key.

Example — a small constant table and lookup table, each read with the functor above that matches its shape:

myLookupTable := LookupTable [
"Key" "Value",
1 10,
2 20,
3 30
];
// lookedUpValue will be 20.
lookedUpValue := GetLookupTableValue myLookupTable 2;
myTable := Table [
"CityId*", "Population", "Area",
1, 667137, 125,
2, 39398, 6
];
// population will be 667137.
population := GetTableValue myTable 1 "Population";
// wholeRow will be the two-element Tuple (39398, 6) — Population then Area.
wholeRow := GetTableRow 2 myTable;

Iterating over Lookup Table values

A For Each loop run over a connected Lookup Table executes once per key. Inside the loop, a Step functor retrieves the current key — its input auto-binds to the container's current iteration value, the same mechanism described in Internal output ports, so it needs no explicit wiring. From there, the key can be used directly, or passed to Get Lookup Table Value to retrieve the corresponding value.

A loop like this can often run its iterations in parallel — see Basic Data Flow for the conditions that allow it.

Example — printing every entry of a Lookup Table. Print is itself a container — its initialMessage is printed before whatever it contains runs, so an empty {{ }} block is enough when the only goal is to print something. Create String builds a message from a format string and the values connected inside it, referenced the same way a Code expression references a hook (see Verbose form) — by a numbered, type-prefixed tag (<v1> for the first connected value, and so on). This example also uses { initialMessage = message } nominal syntax for Print, and the _ discard convention for outputs that aren't needed:

myLookupTable := LookupTable [
"Key" "Value",
1 10,
2 20,
3 30
];
_ := ForEach myLookupTable {{
key := Step;
value := GetLookupTableValue myLookupTable key;
message := CreateString "(Key: <v1>, Value: <v2>)" {{
NumberValue key 1;
NumberValue value 2;
}};
_ := Print { initialMessage = message } {{ }};
}};

Iterating over Table rows

Table rows are iterated the same way, but need one extra functor: Get Table Keys returns a table mapping unique indices to the keys of the input table's first key column. When the key column is already Real-typed, those indices and the keys are the same numbers, so the mapping is trivial. When the key column is String-typed, the indices are distinct numeric placeholders, and a GetTableValue call inside the loop is needed to map the current index back to its actual String key — this indirection is why String-typed key columns are usually avoided when a table will be iterated (see Table Type).

A table with more than one key column can only be iterated one key column at a time this way. To examine every key column, nest loops — see Sub-Tables below.

Example — printing every entry of a Table with a Real-typed key column. General tables are wrapped in Table rather than Lookup Table:

myTable := Table [
"CityId*", "Population",
1, 667137,
2, 39398
];
allKeys := GetTableKeys myTable;
_ := ForEach allKeys {{
key := Step;
value := GetTableValue myTable key "Population";
message := CreateString "(Key: <v1>, Value: <v2>)" {{
NumberValue key 1;
NumberValue value 2;
}};
_ := Print { initialMessage = message } {{ }};
}};

Example — the same, but with a String-typed key column. This is the extra-indirection case described above: GetTableKeys returns indices, not the original keys, so an extra GetTableValue inside the loop maps each index back to its String key before it can be used:

// #string is redundant here — quoted values like "Boston" already infer as String —
// it's included only to make the key column's type explicit at a glance.
myStringKeyedTable := Table [
"CityName*#string", "Population",
"Boston", 667137,
"Chelsea", 39398
];
indexToKey := GetTableKeys myStringKeyedTable;
_ := ForEach indexToKey {{
index := Step;
key := GetTableValue indexToKey index 2;
value := GetTableValue myStringKeyedTable key "Population";
message := CreateString "(Key: <s1>, Value: <v1>)" {{
NumberString key 1;
NumberValue value 1;
}};
_ := Print { initialMessage = message } {{ }};
}};

Example — a table with more than one value column. Nothing new is needed: call GetTableValue once per value column and combine the results:

myTable := Table [
"CityId*", "Population", "Area",
1, 667137, 125,
2, 39398, 6
];
allKeys := GetTableKeys myTable;
_ := ForEach allKeys {{
key := Step;
population := GetTableValue myTable key "Population";
area := GetTableValue myTable key "Area";
message := CreateString "(CityId: <v1>, Population: <v2>, Area: <v3>)" {{
NumberValue key 1;
NumberValue population 2;
NumberValue area 3;
}};
_ := Print { initialMessage = message } {{ }};
}};

Sub-Tables

A sub-table is a table containing only the rows matching one specific value of a key, with that key column removed from the result. Sub-tables are how Dinamica handles tables with more than one key column: peel off one key at a time, working with what remains.

GetTableFromKey

Retrieves the rows matching the given key(s), with those key columns dropped from the result.

Parameter	Type	Required?	Description
table	Table	Yes	The table to read from.
keys	Tuple	Yes	The leftmost key(s) identifying the sub-table.

Output: the matching sub-table.

SetTableByKey

Inserts or replaces the rows matching the given key(s).

Parameter	Type	Required?	Description
table	Table	Yes	The table to update.
keys	Tuple	Yes	The leftmost key(s) identifying where the sub-table goes.
subTable	Table	Yes	The replacement rows. Column names and types must match table.

Output: the updated table.

Both Get Table From Key and Set Table By Key only operate on the table's leftmost key column(s) — they can't reach into the middle of a composite key. If the key you need isn't leftmost, reorder the columns first with Reorder Table Column, which moves one column (key or value) to a new index; key and value columns can't be moved across each other.

Worked example. Take a table of commodity prices, keyed by Year and City:

Year*	City*	Price
2004	4534272	1200
2004	5483552	1453
2007	4534272	4332
2007	5483552	233

Retrieving the sub-table for Year 2007 — a single key, since Year is leftmost — leaves City/Price pairs:

City*	Price
4534272	4332
5483552	233

To instead retrieve by City first, Year would need to be reordered ahead of it, since GetTableFromKey can only key off the leftmost column(s). With three key columns, the same idea nests: peel off the leftmost key to get a sub-table, then peel off the next leftmost key of that sub-table, and so on — which is exactly how nested ForEach loops iterate a multi-key table one column at a time; see Container functors for how nesting containers this way affects execution order.

Example — building the table above, retrieving the 2007 sub-table, updating one of its prices with Set Table Cell Value, writing it back, and finally reordering City ahead of Year to key by City instead:

priceTable := Table [
"Year*", "City*", "Price",
2004, 4534272, 1200,
2004, 5483552, 1453,
2007, 4534272, 4332,
2007, 5483552, 233
];
// Retrieve the City*/Price sub-table for Year 2007.
pricesIn2007 := GetTableFromKey priceTable 2007;
// Replace the price for city 5483552 within that sub-table.
updatedPricesIn2007 := SetTableCellValue pricesIn2007 "Price" 5483552 999;
// Write the modified sub-table back under the same key.
priceTable2 := SetTableByKey priceTable 2007 updatedPricesIn2007;
// Move City (currently index 2) ahead of Year (index 1), so sub-tables can
// instead be retrieved by City first.
priceTableByCity := ReorderTableColumn priceTable2 "City" 1;
// citySubTable will be the Year*/Price pairs for city 4534272.
citySubTable := GetTableFromKey priceTableByCity 4534272;

Example — printing every entry of a table with more than one key column. Get Table Keys only ever iterates the first key column, so a table with several needs one nested loop per extra key: peel off a sub-table for each Year, then iterate the City key within it:

priceTable := Table [
"Year*", "City*", "Price",
2004, 4534272, 1200,
2004, 5483552, 1453,
2007, 4534272, 4332,
2007, 5483552, 233
];
yearKeys := GetTableKeys priceTable;
_ := ForEach yearKeys {{
year := Step;
pricesInYear := GetTableFromKey priceTable year;
cityKeys := GetTableKeys pricesInYear;
_ := ForEach cityKeys {{
city := Step;
price := GetTableValue pricesInYear city "Price";
message := CreateString "(Year: <v1>, City: <v2>, Price: <v3>)" {{
NumberValue year 1;
NumberValue city 2;
NumberValue price 3;
}};
_ := Print { initialMessage = message } {{ }};
}};
}};

Storing results across a loop

A Mux Table or Mux Lookup Table can carry a Table or Lookup Table across the iterations of a loop, the same way Mux Value carries a single value — see Carrying and selecting values across iterations. Each iteration reads the mux's current output, adds a row to it with AddTableRow, and feeds the result back in as the mux's feedback input for the next iteration, building up a result table one row at a time.

Neither For Each nor While/Do While has a data output of its own — each only has a sequencing output, per its own entry in the functor catalog. So there's no dedicated port to “collect” the final accumulated table once the loop ends. Instead, a functor placed outside the loop simply references the accumulator's feedback variable directly, the same way any functor can reference a variable produced inside a container; per Basic Data Flow, that reference is itself a dependency on the whole loop, so Dinamica waits for every iteration to finish before evaluating it.

sourceLookup := LookupTable [
"Key" "Value",
1 667137,
2 39398,
3 181045
];
emptyResults := Table [
"CityId*#real", "DoubledPopulation#real"
];
_ := ForEach sourceLookup {{
accumulated := MuxTable emptyResults nextAccumulated;
key := Step;
population := GetLookupTableValue sourceLookup key;
doubled := $ [ $population * 2 ];
newRow := AddTupleValue key doubled;
nextAccumulated := AddTableRow accumulated newRow;
}};
// finalResults holds every row added across every iteration, not just the
// last one — accumulated (the mux's own output) would lag one iteration behind.
// A bare `finalResults := nextAccumulated;` isn't valid — := always binds the
// result of a functor call, never just another variable's name — so the Table
// carrier functor is used here to re-expose the value under a new binding.
finalResults := Table nextAccumulated;

Why this isn't the best approach. Basic Data Flow documents three conditions under which a loop's iterations can run simultaneously: no mux directly inside the loop, nothing produced inside the loop consumed outside it, and no loop member used as a submodel's output port. A mux-based accumulator like the one above breaks the first condition outright — the mux ties every iteration to the one before it, so the loop can never run as anything but sequential, even when the per-iteration work is otherwise completely independent, as it is above (each row's value depends only on that row's own key).

When the transformation is this simple — one output row per input row, computed independently — the calculator shorthand already covered in Lookup Table Operators produces the same result without a loop, a mux, or the sequential cost that comes with one:

doubledResults := % [ %sourceLookup[line] * 2 ] "CityId" "DoubledPopulation" sourceLookup;

Choosing between Tables and Lookup Tables

A Lookup Table's fixed shape — one Real key, one Real value — makes it faster to query and iterate than a general Table, and it supports proximity-based lookups (nearest key, linear interpolation) that Tables don't. Prefer a Lookup Table whenever the data actually fits that shape, including inside map/value expressions, where Lookup Table operands add less evaluation overhead than Table operands — see Lookup Table Operators and Multi-Column Table Operators for how each is queried from within an expression.

Reach for a general Table instead when a single value per key isn't enough — when a row needs more than one associated value, or a String value, or when rows need to be indexed by more than one key at once.