List Processing (Part 7) – Hashes and Groups


Hashes are containers for data, where each data item has an associated key.

This example has a person’s name as a key, and their suburb of residence as the value.
Using this structure we can then use HASH_GET($hash, $key) to quickly search for a value.

LET $hash := HASH(
    "Stuart", "Greensborough", // key, then value
    "Bert", "Mitcham",
    "Wei", "Bundoora"
RETURN HASH_GET($hash, "Stuart") // evaluates to "Greensborough"

This is often a convenient way to combine data from multiple sources.
You may use any data type as a key or value, including arrays or even hashes.
A common pattern involves using multi-part keys in the form of arrays.

LET $hash := HASH(
    ARRAY("Stuart", 2014), "Viewbank",
    ARRAY("Stuart", 2015), "Greensborough"
RETURN HASH_GET($hash, ARRAY("Stuart", 2014))

// evaluates to “Viewbank”
If you are pulling data from a DB_LOOKUPALL you will often have an array of values as a value:

LET $hash := HASH(
    "1", ARRAY(1, "March", "Greensborough"),
    "2", ARRAY(1, "April", "Mitcham"),
    "3", ARRAY(1, "May", "Bundoora")
RETURN HASH_GET($hash, "1") // evaluates to (1, "March", "Greensborough")

To create a hash, you will use one of: HASH, ARRAY_TO_HASH, ARRAY_TO_HASH_GROUPED.


Definition: Hash HASH(Any $key1, Any $value1,.. Any $keyN, Any $valueN)

This is a basic hash construction function, which can be used to assemble a hash from a fixed set of data. This is often useful for providing data to a ReportingTable or other reporting controls.


Definition: Any HASH_GET(Hash hash, Any $key)

From a given hash, get the value associated with key $key.


Definition: Hash ARRAY_TO_HASH(Array items, $(index, item) getKey, $(index, item) getValue)

This function will take any array, and create a hash with one key/value pair per item in the original array.

LET $source := // below array


	$(i, item) ARRAY_INDEX($item, 2), // key: name
	$(i, item) ARRAY_INDEX($item, 3), // value: suburb


Some examples:

HASH_GET($hash, "Stuart") // result is Greensborough
HASH_GET($hash, "Bert")   // result is Mitcham
HASH_GET($hash, "Wei")    // result is Bundoora


There are two functions that make it easy to split apart a list into groups: ARRAY_GROUP, and ARRAY_TO_HASH_GROUPED.


Definition: Hash ARRAY_TO_HASH_GROUPED(Array items, $(index, item) getKey, $(index, item) getValue)

This function is very similar to ARRAY_TO_HASH, with the exception that it is assumed that there might be more than one item with the same key. As a result, each ‘value’ is an array of all values from the original that had the same key.

LET $source := // below array


	$(i, item) ARRAY_INDEX($item, 3), // key: suburb
	$(i, item) ARRAY_INDEX($item, 2), // value: name


HASH_GET($hash, "Greensborough") // result is ["Stuart", "James"]
HASH_GET($hash, "Bundoora") // result is ["Wei", "Lana"]
HASH_GET($hash, "Jeremy") // result is ["Jeremy"]


LET $source := // below array


	$(i, item) ARRAY_INDEX($item, 3) // key: suburb


This is quite a complex structure to deal with, although it has the added benefit that it is grouped in a stable fashion, so each group will appear in the results in the order first encountered.

Related Articles