====== Set Table By Key ======

===== Description =====

This functor updates or inserts a sub-table corresponding to the given chain of keys into a table.

===== Inputs =====

^ Name  ^ Type  ^ Description  ^
| Table  | [[Table Type]]  | The input table.  |
| Keys  | [[Tuple Type]]  | Chain of keys identifying the sub-table that will be updated or insert.  |
| Sub Table  | [[Table Type]]  | Sub-table that will be inserted into 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.   |

===== Outputs =====

^ Name  ^ Type  ^ Description  ^
| Result  | [[Table Type]]  | The resulting table.  |

===== Group =====

[[Functor List#Table|Table]]

===== Notes =====

This functor inserts elements corresponding to the given tuple of keys into the input table.

**Example 1:**

Given the table below

^ Key1*  ^ Key2*  ^ Key3*  ^ Value1  ^ Value2  ^ Value3  ^
| 1  | "a"  | 11  | 12  | "bbbb"  | 23  |
| 1  | "b"  | 22  | 12  | "cccc"  | 23  |
| 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",

^ Key3*  ^ Value1  ^ Value2  ^ Value3  ^
|@#C5D9FF: 11  |@#C5D9FF: 12  |@#C5D9FF: "bbbb"  |@#C5D9FF: 14  |
|@#C5D9FF: 22  |@#C5D9FF: 12  |@#C5D9FF: "aaaa"  |@#C5D9FF: 23  |

results in

^ Key1*  ^ Key2*  ^ Key3*  ^ Value1  ^ Value2  ^ Value3  ^
| 1  | "a"  | 11  | 12  | "bbbb"  | 23  |
| 1  | "b"  | 22  | 12  | "cccc"  | 23  |
|@#CCFFCC: 2  |@#CCFFCC: "a"  |@#C5D9FF: 11  |@#C5D9FF: 12  |@#C5D9FF: "bbbb"  |@#C5D9FF: 14  |
|@#CCFFCC: 2  |@#CCFFCC: "a"  |@#C5D9FF: 22  |@#C5D9FF: 12  |@#C5D9FF: "aaaa"  |@#C5D9FF: 23  |
| 2  | "d"  | 22  | 12  | "dddd"  | 12  |

**Example 2**:

Inserting the sub-table corresponding to the tuple of keys ''<2>'', where 2 corresponds to column "Key1", 

^ Key2*  ^ Key3*  ^ Value1  ^ Value2  ^ Value3  ^
|@#C5D9FF: "a"  |@#C5D9FF: 11  |@#C5D9FF: 12  |@#C5D9FF: "bbbb"  |@#C5D9FF: 14  |
|@#C5D9FF: "a"  |@#C5D9FF: 22  |@#C5D9FF: 12  |@#C5D9FF: "aaaa"  |@#C5D9FF: 23  |
|@#C5D9FF: "d"  |@#C5D9FF: 22  |@#C5D9FF: 12  |@#C5D9FF: "dddd"  |@#C5D9FF: 12  |

results in

^ Key1*  ^ Key2*  ^ Key3*  ^ Value1  ^ Value2  ^ Value3  ^
| 1  | "a"  | 11  | 12  | "bbbb"  | 23  |
| 1  | "b"  | 22  | 12  | "cccc"  | 23  |
|@#CCFFCC: 2  |@#C5D9FF: "a"  |@#C5D9FF: 11  |@#C5D9FF: 12  |@#C5D9FF: "bbbb"  |@#C5D9FF: 14  |
|@#CCFFCC: 2  |@#C5D9FF: "a"  |@#C5D9FF: 22  |@#C5D9FF: 12  |@#C5D9FF: "aaaa"  |@#C5D9FF: 23  |
|@#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 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.

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 Column]] functor.

===== Internal Name =====

SetTableByKey