====== Get Table From Key ======

===== Description =====

This functor retrieves the sub-table corresponding to the given chain of keys from a given input table.

===== Inputs =====

^ Name  ^ Type  ^ Description  ^
| Table  | [[Table Type]]  | The input table.  |
| Keys  | [[Tuple Type]]  | Chain of keys identifying the sub-table that will be retrieved.  |

===== Outputs =====

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

===== Group =====

[[Functor List#Table|Table]]

===== Notes =====

This functor retrieves all elements corresponding to the given tuple of keys in 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  | "a"  | 11  | 12  | "bbbb"  | 14  |
| 2  | "a"  | 22  | 12  | "aaaa"  | 23  |
| 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",

^ 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  

results in

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

**Example 2:**

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

^ 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  |

results in

^ 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  |

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.

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.

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

GetTableFromKey