group( rset, field, ... )

Groups a result set by one or more fields. By far the easiest way to explain the group function is by example, so let's consider different groupings for the following result set: 

:-) var results = {
:-)   newMap( "id" ==> "a", "design" ==> "1", "name" ==> "Elias" ),
:-)   newMap( "id" ==> "b", "design" ==> "1", "name" ==> "Alexander" ),
:-)   newMap( "id" ==> "c", "design" ==> "1", "name" ==> "Isabelle" ),
:-)   newMap( "id" ==> "d", "design" ==> "1", "name" ==> "Eirene" ),
:-)   newMap( "id" ==> "e", "design" ==> "1", "name" ==> "Isabelle" ),
:-)   newMap( "id" ==> "f", "design" ==> "2", "name" ==> "Kisha" ),
:-)   newMap( "id" ==> "g", "design" ==> "2", "name" ==> "Martina" ),
:-)   newMap( "id" ==> "h", "design" ==> "2", "name" ==> "Xavier" ),
:-)   newMap( "id" ==> "i", "design" ==> "2", "name" ==> "Xavier" ),
:-)   newMap( "id" ==> "j", "design" ==> "3", "name" ==> "Mikolás" ),
:-)   newMap( "id" ==> "k", "design" ==> "3", "name" ==> "Scrapper" ),
:-)   newMap( "id" ==> "l", "design" ==> "3", "name" ==> "Elias" ),
:-)   newMap( "id" ==> "m", "design" ==> "4", "name" ==> "Martina" ),
:-)   newMap( "id" ==> "n", "design" ==> "4", "name" ==> "Mervin" ),
:-)   newMap( "id" ==> "o", "design" ==> "5", "name" ==> "Kisha" ),
:-)   newMap( "id" ==> "p", "design" ==> "6", "name" ==> "Martina" )
:-) };

Single level grouping

Let's consider the simplest case of grouping by one field. This will return a map, where the different field values map to the subset of the result set that share that field value, e.g. 

:-) group( results, "id" );
There is 1 result
{
  a=[{name=Elias, design=1, id=a}],
  b=[{name=Alexander, design=1, id=b}],
  c=[{name=Isabelle, design=1, id=c}],
  d=[{name=Eirene, design=1, id=d}],
  e=[{name=Isabelle, design=1, id=e}],
  f=[{name=Kisha, design=2, id=f}],
  g=[{name=Martina, design=2, id=g}],
  h=[{name=Xavier, design=2, id=h}],
  i=[{name=Xavier, design=2, id=i}],
  j=[{name=Mikolás, design=3, id=j}],
  k=[{name=Scrapper, design=3, id=k}],
  l=[{name=Elias, design=3, id=l}],
  m=[{name=Martina, design=4, id=m}],
  n=[{name=Mervin, design=4, id=n}],
  o=[{name=Kisha, design=5, id=o}],
  p=[{name=Martina, design=6, id=p}]
}

So the results above show that the group function returns a map, whose keys are each of the unique values of the id field in the result set. The values associated with the keys are lists of maps, where each map has the same value for the id field.

In our original result set, we had a result where the id field contained "a", the design field contained "1" and the name field contained "Elias", e.g. 

newMap( "id" ==> "a", "design" ==> "1", "name" ==> "Elias" )

In the map returned from the group function, there is a key with the value "a", which was one of the unique values of the id field. The value associated with this key is a list, which contains one map. It only contains one map because there was only one record in our result set where the id field contained the value "a". e.g. we get the following key-value pair set in the map returned from the group function: 

a=[
  {name=Elias, design=1, id=a}
]

This allows us to easily access all values in our results whose id field is "a", e.g. 

:-) var groupedById = group( results, "id" );
There are 0 results
:-) groupedById[ "a" ];
There is 1 result
[{name=Elias, design=1, id=a}]

Now for a different example of grouping by one field. This time we will group by the design field, e.g. 

:-) group( results, "design" );
There is 1 result
{
  1=[
    {name=Elias, design=1, id=a},
    {name=Alexander, design=1, id=b},
    {name=Isabelle, design=1, id=c},
    {name=Eirene, design=1, id=d},
    {name=Isabelle, design=1, id=e}
  ],
  2=[
    {name=Kisha, design=2, id=f},
    {name=Martina, design=2, id=g},
    {name=Xavier, design=2, id=h},
    {name=Xavier, design=2, id=i}
  ],
  3=[
    {name=Mikolás, design=3, id=j},
    {name=Scrapper, design=3, id=k},
    {name=Elias, design=3, id=l}
  ],
  4=[
    {name=Martina, design=4, id=m},
    {name=Mervin, design=4, id=n}
  ],
  5=[{name=Kisha, design=5, id=o}],
  6=[{name=Martina, design=6, id=p}]
}

This time there are some records in the result set that have the same value for the design field. Let's consider those records whose design field contains the value "1", e.g. 

newMap( "id" ==> "a", "design" ==> "1", "name" ==> "Elias" )
newMap( "id" ==> "b", "design" ==> "1", "name" ==> "Alexander" )
newMap( "id" ==> "c", "design" ==> "1", "name" ==> "Isabelle" )
newMap( "id" ==> "d", "design" ==> "1", "name" ==> "Eirene" )
newMap( "id" ==> "e", "design" ==> "1", "name" ==> "Isabelle" )

This time in the map returned by the group function, there is a key with the value "1". The value associated with this key is a list of maps, which contains 5 maps. Each of these 5 maps has the value "1" in the design field, e.g. 

1=[
  {name=Elias, design=1, id=a},
  {name=Alexander, design=1, id=b},
  {name=Isabelle, design=1, id=c},
  {name=Eirene, design=1, id=d},
  {name=Isabelle, design=1, id=e}
]

Just to be complete, lets also include an example for grouping by the name field as well. e.g. 

:-) group( results, "name" );
There is 1 result
{
  Alexander=[{name=Alexander, design=1, id=b}],
  Eirene=[{name=Eirene, design=1, id=d}],
  Elias=[
    {name=Elias, design=1, id=a},
    {name=Elias, design=3, id=l}
  ],
  Isabelle=[
    {name=Isabelle, design=1, id=c},
    {name=Isabelle, design=1, id=e}
  ],
  Kisha=[
    {name=Kisha, design=2, id=f},
    {name=Kisha, design=5, id=o}
  ],
  Martina=[
    {name=Martina, design=2, id=g},
    {name=Martina, design=4, id=m}
    {name=Martina, design=6, id=p}
  ],
  Mervin=[{name=Mervin, design=4, id=n}],
  Mikolás=[{name=Mikolás, design=3, id=j}],
  Scrapper=[{name=Scrapper, design=3, id=k}],
  Xavier=[
    {name=Xavier, design=2, id=h},
    {name=Xavier, design=2, id=i}
  ]
}

Multiple level grouping

Finally lets consider a more complex example. This time lets group the data by two fields, name then design. From the previous examples of a "single level" group, we would expect a map from names to a list of results sharing each name. However, this time, instead of the list of results, we get a grouping of that list of results by the design field, e.g. 

:-) group( results, "name", "design" );
There is 1 result
{
  Alexander={
    1=[{name=Alexander, design=1, id=b}]
  },
  Eirene={
    1=[{name=Eirene, design=1, id=d}]
  },
  Elias={
    1=[{name=Elias, design=1, id=a}],
    3=[{name=Elias, design=3, id=l}]
  },
  Isabelle={
    1=[
      {name=Isabelle, design=1, id=c},
      {name=Isabelle, design=1, id=e}
    ]
  },
  Kisha={
    2=[{name=Kisha, design=2, id=f}],
    5=[{name=Kisha, design=5, id=o}]
  },
  Martina={
    2=[{name=Martina, design=2, id=g}],
    4=[{name=Martina, design=4, id=m}],
    6=[{name=Martina, design=6, id=p}]
  },
  Mervin={
    4=[{name=Mervin, design=4, id=n}]
  },
  Mikolás={
    3=[{name=Mikolás, design=3, id=j}]
  },
  Scrapper={
    3=[{name=Scrapper, design=3, id=k}]
  },
  Xavier={
    2=[
      {name=Xavier, design=2, id=h},
      {name=Xavier, design=2, id=i}
    ]
  }
}

This time there are some records in the result set that have the same value for the name field. Let's consider the those records whose name field contains the value "Martina", e.g. 

newMap( "id" ==> "g", "design" ==> "2", "name" ==> "Martina" )
newMap( "id" ==> "m", "design" ==> "4", "name" ==> "Martina" )
newMap( "id" ==> "p", "design" ==> "6", "name" ==> "Martina" )

This time in the map returned by the group function, there is a key with the value "Martina". The value associated with this key is a map, which is the grouping of the above results by the design field, e.g. 

Martina={
  2=[{name=Martina, design=2, id=g}],
  4=[{name=Martina, design=4, id=m}],
  6=[{name=Martina, design=6, id=p}]
}

The were three different values for the design field, where the name contained "Martina". Hence the map associated with the key "Martina" has three keys defined, whose values are lists of maps. These lists of maps contain those results whose value of name and design are the same.

This allows us to easily access all values in our results whose name field contains "Martina" and whose design field contains "4", e.g. 

:-) var groupedByNameByDesign = group( results, "name", "design" );
There are 0 results
:-) groupedByNameByDesign[ "Martina" ][ "4" ];
There is 1 result
[{name=Martina, design=4, id=m}]