Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
|
set_table_by_key [2013/08/06 18:50] admin created |
set_table_by_key [2026/08/28 03:34] (current) hermann Sync from local documentation review |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| ===== Description ===== | ===== Description ===== | ||
| - | This functor updates or inserts a sub-table corresponding to the given chain of keys in a table. | + | Updates or inserts the sub-table corresponding to a given chain of keys in a 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 updated or insert. | | + | | Keys | [[Tuple Type]] | Chain of keys, starting from the first key column, identifying the sub-table that will be updated or inserted. | |
| - | | Sub Table | [[Table Type|Table]] | Sub-table that will be inserted in the input table. The column names in the sub-table must match the corresponding names in the input table. The column types must also be compatible. | | + | | Sub Table | [[Table Type]] | Sub-table that will be inserted into Table. Its column names must match the corresponding names in Table, or this functor reports an error, unless Ignore Column Names is set. Its column types must also be compatible. | |
| + | |||
| + | ===== Optional Inputs ===== | ||
| + | |||
| + | ^ Name ^ Type ^ Description ^ Default Value ^ | ||
| + | | Ignore Column Names | [[Boolean Value Type]] | If true, Sub Table's column names are not validated against Table's corresponding columns. | False | | ||
| + | | Combine Sub Tables | [[Boolean Value Type]] | If true, Sub Table is merged into the existing sub-table already present at the given keys, instead of replacing it. | False | | ||
| ===== Outputs ===== | ===== Outputs ===== | ||
| - | ^ Name ^ Type ^ Description ^ | + | ^ Name ^ Type ^ Description ^ |
| - | | Result | [[Table Type|Table]] | The resulting table. | | + | | Result | [[Table Type]] | The resulting table. | |
| ===== Group ===== | ===== Group ===== | ||
| - | [[Functor List#Table|Table]] | + | [[Functor List#Table | Table]] |
| ===== Notes ===== | ===== Notes ===== | ||
| - | This functor inserts elements corresponding to the given tuple of keys in the input table. For example, given the table below | + | Keys is matched against Table's key columns starting from the leftmost one, the same way as in [[Get Table From Key]]; it is not possible to index by key columns other than a prefix of the leftmost ones. To index by a different key column, first bring it to the front with [[Reorder Table Column]]. |
| + | |||
| + | **Example 1:** | ||
| + | |||
| + | Given the table below | ||
| ^ Key1* ^ Key2* ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | ^ Key1* ^ Key2* ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | ||
| Line 30: | Line 40: | ||
| | 2 | "d" | 22 | 12 | "dddd" | 12 | | | 2 | "d" | 22 | 12 | "dddd" | 12 | | ||
| - | inserting a sub-table corresponding to the tuple of keys ''<2, "a">'', where 2 corresponds to column "Key1" and "a" corresponds to column "Key2", | + | inserting a sub-table corresponding to the tuple of keys <2, "a">, where 2 corresponds to column "Key1" and "a" corresponds to column "Key2", |
| ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | ||
| - | |@green: 11 |@green: 12 |@green: "bbbb" |@green: 14 | | + | |@#C5D9FF: 11 |@#C5D9FF: 12 |@#C5D9FF: "bbbb" |@#C5D9FF: 14 | |
| - | |@green: 22 |@green: 12 |@green: "aaaa" |@green: 23 | | + | |@#C5D9FF: 22 |@#C5D9FF: 12 |@#C5D9FF: "aaaa" |@#C5D9FF: 23 | |
| - | yelds | + | results in |
| ^ Key1* ^ Key2* ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | ^ Key1* ^ Key2* ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | ||
| | 1 | "a" | 11 | 12 | "bbbb" | 23 | | | 1 | "a" | 11 | 12 | "bbbb" | 23 | | ||
| | 1 | "b" | 22 | 12 | "cccc" | 23 | | | 1 | "b" | 22 | 12 | "cccc" | 23 | | ||
| - | |@lightgreen: 2 |@lightgreen: "a" |@green: 11 |@green: 12 |@green: "bbbb" |@green: 14 | | + | |@#CCFFCC: 2 |@#CCFFCC: "a" |@#C5D9FF: 11 |@#C5D9FF: 12 |@#C5D9FF: "bbbb" |@#C5D9FF: 14 | |
| - | |@lightgreen: 2 |@lightgreen: "a" |@green: 22 |@green: 12 |@green: "aaaa" |@green: 23 | | + | |@#CCFFCC: 2 |@#CCFFCC: "a" |@#C5D9FF: 22 |@#C5D9FF: 12 |@#C5D9FF: "aaaa" |@#C5D9FF: 23 | |
| | 2 | "d" | 22 | 12 | "dddd" | 12 | | | 2 | "d" | 22 | 12 | "dddd" | 12 | | ||
| - | and retrieving the sub-table corresponding to the tuple of keys ''<2>'', where 2 corresponds to column "Key1", | + | **Example 2:** |
| + | |||
| + | Inserting the sub-table corresponding to the tuple of keys <2>, where 2 corresponds to column "Key1", | ||
| ^ Key2* ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | ^ Key2* ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | ||
| - | |@green: "a" |@green: 11 |@green: 12 |@green: "bbbb" |@green: 14 | | + | |@#C5D9FF: "a" |@#C5D9FF: 11 |@#C5D9FF: 12 |@#C5D9FF: "bbbb" |@#C5D9FF: 14 | |
| - | |@green: "a" |@green: 22 |@green: 12 |@green: "aaaa" |@green: 23 | | + | |@#C5D9FF: "a" |@#C5D9FF: 22 |@#C5D9FF: 12 |@#C5D9FF: "aaaa" |@#C5D9FF: 23 | |
| - | |@green: "d" |@green: 22 |@green: 12 |@green: "dddd" |@green: 12 | | + | |@#C5D9FF: "d" |@#C5D9FF: 22 |@#C5D9FF: 12 |@#C5D9FF: "dddd" |@#C5D9FF: 12 | |
| - | yelds | + | results in |
| ^ Key1* ^ Key2* ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | ^ Key1* ^ Key2* ^ Key3* ^ Value1 ^ Value2 ^ Value3 ^ | ||
| | 1 | "a" | 11 | 12 | "bbbb" | 23 | | | 1 | "a" | 11 | 12 | "bbbb" | 23 | | ||
| | 1 | "b" | 22 | 12 | "cccc" | 23 | | | 1 | "b" | 22 | 12 | "cccc" | 23 | | ||
| - | |@lightgreen: 2 |@green: "a" |@green: 11 |@green: 12 |@green: "bbbb" |@green: 14 | | + | |@#CCFFCC: 2 |@#C5D9FF: "a" |@#C5D9FF: 11 |@#C5D9FF: 12 |@#C5D9FF: "bbbb" |@#C5D9FF: 14 | |
| - | |@lightgreen: 2 |@green: "a" |@green: 22 |@green: 12 |@green: "aaaa" |@green: 23 | | + | |@#CCFFCC: 2 |@#C5D9FF: "a" |@#C5D9FF: 22 |@#C5D9FF: 12 |@#C5D9FF: "aaaa" |@#C5D9FF: 23 | |
| - | |@lightgreen: 2 |@green: "d" |@green: 22 |@green: 12 |@green: "dddd" |@green: 12 | | + | |@#CCFFCC: 2 |@#C5D9FF: "d" |@#C5D9FF: 22 |@#C5D9FF: 12 |@#C5D9FF: "dddd" |@#C5D9FF: 12 | |
| - | If there is already a sub-table corresponding to the sub-table being inserted in the sub-table, the existent sub-table is replaced by the new sub-table. The same is true if the sub-table being inserted is empty. In this case, the existent sub-table is removed from the input table. | + | If a sub-table already exists at the given keys, it is replaced by Sub Table (or merged with it, if Combine Sub Tables is true). If Sub Table is empty, the existing sub-table at those keys, if any, is removed from Table. |
| - | It is not possible to insert a sub-table indexed by keys from arbitrary key columns. For example, in the example above, it is not possible to insert 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 Columns]] functor. | + | If the given keys are not yet present in Table and Sub Table is empty, this functor has no effect. |
| + | |||
| + | Table's own column names are always used as the column names of the resulting table, regardless of Ignore Column Names. | ||
| ===== Internal Name ===== | ===== Internal Name ===== | ||
| SetTableByKey | SetTableByKey | ||
| + | |||
| + | ===== Usage examples ===== | ||
| + | |||
| + | See practical examples of this functor in [[lesson_7|Lesson 7: Creating a new column and retrieving a data column from tables]] | ||