Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
get_table_from_key [2013/08/09 20:27] admin [Notes] |
get_table_from_key [2026/08/28 03:22] (current) hermann Sync from local documentation review |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| ===== Description ===== | ===== Description ===== | ||
| - | This functor retrieves the sub-table corresponding to the given chain of keys from a given input table. | + | Retrieves the sub-table corresponding to a given chain of keys from an input table. |
| ===== Inputs ===== | ===== Inputs ===== | ||
| ^ Name ^ Type ^ Description ^ | ^ Name ^ Type ^ Description ^ | ||
| - | | Table | [[Table Type|Table]] | The input table. | | + | | Table | [[Table Type]] | The input table. | |
| - | | Keys | [[Tuple Type|Tuple]] | Chain of keys identifying the sub-table that will be retrieved. | | + | | Keys | [[Tuple Type]] | Chain of keys, starting from the first key column, identifying the sub-table that will be retrieved. | |
| + | |||
| + | ===== Optional Inputs ===== | ||
| + | |||
| + | None. | ||
| ===== Outputs ===== | ===== Outputs ===== | ||
| - | ^ Name ^ Type ^ Description ^ | + | ^ Name ^ Type ^ Description ^ |
| - | | Result | [[Table Type|Table]] | The resulting sub-table. | | + | | Result | [[Table Type]] | The resulting sub-table. | |
| ===== Group ===== | ===== Group ===== | ||
| - | [[Functor List#Table|Table]] | + | [[Functor List#Table | Table]] |
| ===== Notes ===== | ===== Notes ===== | ||
| - | This functor retrieves all elements corresponding to the given tuple of keys in the input table. | + | Keys is matched against the table's key columns starting from the leftmost one; a tuple with fewer elements than the table's key columns retrieves the sub-table formed by all rows sharing that key prefix, keeping only the remaining (unmatched) key columns. |
| **Example 1:** | **Example 1:** | ||
| Line 35: | Line 39: | ||
| | 2 | "d" | 22 | 12 | "dddd" | 12 | | | 2 | "d" | 22 | 12 | "dddd" | 12 | | ||
| - | retrieving the sub-table corresponding to the tuple of keys ''<2, "a">'', where 2 corresponds to column "Key1" and "a" corresponds to column "Key2", | + | retrieving the sub-table for the key tuple <2, "a"> (Key1=2, Key2="a") results in |
| - | + | ||
| - | ^ Key1* ^ Key2* ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | + | |
| - | | 1 | "a" | 11 | 12 | "bbbb" | 23 | | + | |
| - | | 1 | "b" | 22 | 12 | "cccc" | 23 | | + | |
| - | |@lightgreen: 2 |@lightgreen: "a" |@green: 11 |@green: 12 |@green: "bbbb" |@green: 14 | | + | |
| - | |@lightgreen: 2 |@lightgreen: "a" |@green: 22 |@green: 12 |@green: "aaaa" |@green: 23 | | + | |
| - | | 2 | "d" | 22 | 12 | "dddd" | 12 | + | |
| - | + | ||
| - | results in | + | |
| ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | ||
| - | |@green: 11 |@green: 12 |@green: "bbbb" |@green: 14 | | + | | 11 | 12 | "bbbb" | 14 | |
| - | |@green: 22 |@green: 12 |@green: "aaaa" |@green: 23 | | + | | 22 | 12 | "aaaa" | 23 | |
| **Example 2:** | **Example 2:** | ||
| - | Retrieving the sub-table corresponding to the tuple of keys ''<2>'', where 2 corresponds to column "Key1", | + | Retrieving the sub-table for the key tuple <2> (Key1=2 only) from the same table results in |
| - | ^ Key1* ^ Key2* ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | + | ^ Key2* ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ |
| - | | 1 | "a" | 11 | 12 | "bbbb" | 23 | | + | | "a" | 11 | 12 | "bbbb" | 14 | |
| - | | 1 | "b" | 22 | 12 | "cccc" | 23 | | + | | "a" | 22 | 12 | "aaaa" | 23 | |
| - | |@lightgreen: 2 |@green: "a" |@green: 11 |@green: 12 |@green: "bbbb" |@green: 14 | | + | | "d" | 22 | 12 | "dddd" | 12 | |
| - | |@lightgreen: 2 |@green: "a" |@green: 22 |@green: 12 |@green: "aaaa" |@green: 23 | | + | |
| - | |@lightgreen: 2 |@green: "d" |@green: 22 |@green: 12 |@green: "dddd" |@green: 12 | | + | |
| - | results in | + | It is not possible to retrieve a sub-table indexed by keys taken from arbitrary key columns — only a prefix of the leftmost key columns can be used this way. To index by a different key column, first bring it to the front with [[Reorder Table Column]]. |
| - | + | ||
| - | ^ Key2* ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | + | |
| - | |@green: "a" |@green: 11 |@green: 12 |@green: "bbbb" |@green: 14 | | + | |
| - | |@green: "a" |@green: 22 |@green: 12 |@green: "aaaa" |@green: 23 | | + | |
| - | |@green: "d" |@green: 22 |@green: 12 |@green: "dddd" |@green: 12 | | + | |
| - | If the resulting sub-table does not have at least one column of keys or if the given tuple of keys is not present in the input table, an error is reported. | + | This functor reports an error if the resulting sub-table would have no key columns left, or if the given chain of keys is not present in the input table. |
| - | It is not possible to retrieve a sub-table indexed by keys from arbitrary key columns. For example, in the example above, it is not possible to retrieve a sub-table corresponding to keys ''<2, 22>'', where 2 corresponds to the first column ("Key1") and 22 corresponds to the third column ("Key3"). To do this, first reorder the key columns using the [[Reorder Table Column]] functor. | + | This functor also reports an error if Table is a lookup table, or a table with fewer than two key columns. |
| ===== Internal Name ===== | ===== Internal Name ===== | ||
| GetTableFromKey | GetTableFromKey | ||
| + | |||
| + | ===== Usage examples ===== | ||
| + | |||
| + | See practical examples of this functor in [[lesson_7|Lesson 7: Creating a new column and retrieving a data column from tables]] | ||