indexByPrimaryKey( rset, field )

Indexes a result set by the specified field returning a map from field values to the record in the result set with that field value.

This is similar in behaviour to the group function, except that there is a one-to-one relationship between the field value and the record it relates to. As with the group function it is easiest to explain by example, e.g. consider the following dataset: 

:-) 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" )
:-) };

Let's index this result set by one of it's fields, the id field. This will return a map, where the different field values map to the record with that field value, e.g. 

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

So the results above show that the indexByPrimaryKey function returns a map, whose keys are each of the unique values of the id field in the result set. The value associated with the key is a map, which 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 single map. In fact it can't be anything else as this function requires that the specified field is a primary key, hence all the values of this field must be unique. 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 specific records from the result set, e.g. the record whose id field is "a": 

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

As I've already stated the specified field should be a primary key, hence it's values should be unique. If you supply a non primary key as the field, this function will generate a mishap. e.g. lets try indexing by the "design" field: 

:-) indexByPrimaryKey( results, "design" );


MISHAP  : Multiple records sharing this key
BECAUSE : Primary keys uniquely determine records
RECORD : {name=Alexander, design=1, id=b}
KEY : design
VAL : 1
DOING : <function indexByPrimaryKey>
LINE NO. : 1
PHASE   : Evaluation
Trapped : org.millscript.millscript.Alert$EscapeException
Resetting input and resuming execution

So you can see we get the above error because multiple records in the result set share the same value for the "design" field.