Function Name	Top
Category	Set
Icon
Description	Retrieve the top n items in a sequence
Inputs	Nodes Sequence to retrieve first n values from Count Number of values to retrieve (up to)
Outputs	Result First n items in sequence
Properties	None -

Usage

The Data Mapper Set Top function allows you to retrieve the first n items in a sequence. If the sequence contains less than the count number specified, all items will be mapped - the count value is the maximum number to map. The Top function is particularly useful in conjunction with other functions such as Sort. To apply the Set Top function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using clubs_source.xsd, an XML Schema Definition inferred from the following source:

<sport_clubs>
 <club>
  <name>New Town Football Club</name>
  <member>
   <active>Yes</active>
   <member_name>Chris Black</member_name>
   <member_since>2005</member_since>
   <won>League 2009</won>
   <won>Cup 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Jim Thomson</member_name>
   <member_since>2003</member_since>
   <won>League 2010</won>
  </member>
  <member>
   <active>No</active>
   <member_name>Barry Jones</member_name>
   <member_since>1996</member_since>
   <won>League 1999</won>
   <won>Cup 1999</won>
   <won>League 2000</won>
  </member>
 </club>
 <club>
  <name>City Netball Team</name>
  <member>
   <active>No</active>
   <member_name>Jacqueline Johnson</member_name>
   <member_since>1999</member_since>
   <won>National Championship 2001</won>
   <won>Regional Championship 2002</won>
   <won>National Championship 2002</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Joanne Smith</member_name>
   <member_since>2005</member_since>
   <won>Regional Championship 2007</won>
   <won>National championship 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Mary Owens</member_name>
   <member_since>2007</member_since>
   <won>National Championship 2008</won>
  </member>
 </club>
</sport_clubs>

For our target schema we will be using clubs_target.xsd, inferred from the following XML:

<clubs>
 <team t_name="City Baseball Team">
  <player p_name="Mark Peterson" is_active="yes">
   <joined>1998</joined>
   <title>UK Championship 2000</title>
  </player>
  <player p_name="John Paterson" is_active="yes">
   <joined>2001</joined>
   <title>English Championship 2003</title>
   <title>European Finalists 2004</title>
  </player>
  <player p_name="Barry Thomson" is_active="no">
   <joined>1995</joined>
   <title>English Championship 1997</title>
  </player>
 </team>
 <team t_name="New Town Hockey Team">
  <player p_name="Jill Chapman" is_active="yes">
   <joined>2004</joined>
   <title>National League Championships 2004</title>
  </player>
  <player p_name="Samantha Jackson" is_active="no">
   <joined>1997</joined>
   <title>British Cup 1999</title>
   <title>British Cup 2000</title>
  </player>
  <player p_name="Jane Maxwell" is_active="yes">
   <joined>2003</joined>
   <title>National League Championship 2004</title>
   <title>British Cup 2004</title>
   <title>National League Championship 2005</title>
  </player>
 </team>
</clubs>

The data models sporting clubs and their members. Some of the elements can appear multiple times. Let's assume that, for each "club" element, we want to map the two oldest members, i.e. the two "member" elements with the earliest "member_since" values. Here is the Data Mapper with Source and Target imported:

Drag the Set Top function from the Component Palette into the mapping area:

The Set Top function takes two inputs, representing the nodes to retrieve the items from and the number of items to retrieve. The Nodes input should be connected to the item you are looking to map n instances of within its parent element, while the Count input should be connected to a numerical indicator of the number you want to apply as the maximum. The Mapper will iterate through the nodes, applying the count in the order in which it receives the nodes, retrieving the first n items only. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper.

The output of the Top function naturally depends on the order in which the Mapper receives the nodes. Before we apply the Top function, let's sort the "member" items on their "member_since" values, since we want the two oldest members. Drag a Sort function onto the Mapper, connecting its Nodes input to the "member" output in the XML Reader and its Sort Key input to the "member_since" output. Now the Sort Values output will contain the "member" elements for a club, listed in order of the dates the members joined.

Connect the Sort output to the Nodes input of the Top function, since this is the sequence we want to retrieve the top n values from.

Now we have to define the number of items we want to retrieve. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Select an integer Data Type from the drop-down list and enter the number 2 as the Value, so that we retrieve the first two items in the sequence.

Connect the Constant output to the Count input in the Top function. The Top function will now output the top 2 items in the sorted sequence of "member" elements for each "club" element.

Now we can map the Top function to the output, connecting it to the "player" input in the XML Writer.

Finally let's connect the remaining input and output connections. Remember to map "member_since" to "joined" - although we have used the item as a reference, we have not yet mapped it from Reader to Writer.

We can now execute the transform by pressing Shift-F5 or the Execute button (). The transform is applied and the file we selected as output opens in the editor:

<clubs>
 <team t_name="New Town Football Club">
  <player p_name="Barry Jones" is_active="No">
   <joined>1996</joined>
   <title>League 1999</title>
   <title>Cup 1999</title>
   <title>League 2000</title>
  </player>
  <player p_name="Jim Thomson" is_active="Yes">
   <joined>2003</joined>
   <title>League 2010</title>
  </player>
 </team>
 <team t_name="City Netball Team">
  <player p_name="Jacqueline Johnson" is_active="No">
   <joined>1999</joined>
   <title>National Championship 2001</title>
   <title>Regional Championship 2002</title>
   <title>National Championship 2002</title>
  </player>
  <player p_name="Joanne Smith" is_active="Yes">
   <joined>2005</joined>
   <title>Regional Championship 2007</title>
   <title>National championship 2007</title>
  </player>
 </team>
</clubs>

Each "team" element contains two "player" elements - the two with the earliest "joined" values from the source. In many cases, the Top function proves most useful in conjunction with other functions as in the example above. The Maths, Comparator and Aggregate functions can also be used in combination to achieve detailed results.

If you only need to retrieve the first item in a sequence, you can alternatively use the First function. The Last function retrieves the final item, and the Get At function retrieves the item at a specific index.