Liquid Studio 2020
Data Mapping / Data Mapper Functions / By Category / Set / GetAt
In This Topic
    GetAt
    In This Topic

    Function Name
    Get At
    Category
    Set
    Icon
    Get At
    Description
    Get the value at a specified index within a sequence
    Inputs
    Nodes Sequence to retrieve output from
    Index Index of value to retrieve within nodes (zero-based)
    Outputs
    Result Item at given index within nodes sequence.
    The output takes its type from the input Nodes, see Dynamic Output Values.
    Properties
    None -

    Usage

    The Data Mapper Set Get At function allows you to map items at a particular index within a set of nodes in your XML source. As with many of the Set functions, you may find the Get At function particularly useful when used with other functions. For example, the Get At function in conjunction with the Sort function allows you to retrieve items at particular points in a sorted set. To apply the Set Get At 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 and the following XML source:

    Source XML
    Copy Code
    <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

    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 "member" with the second earliest "member_since" date value, i.e. the second longest standing member. Here is the Data Mapper with Source and Target imported:

    Data Mapper Source and Target

    Drag the Set Get At function from the Component Palette into the mapping area:

    Set Get At Component

    Get At Transform Added

    The Set 'Get At' function takes two inputs, representing the nodes to retrieve the item from and the index to retrieve it from. The Nodes input should be connected to the item you are looking to map an instance of, while the Index input should be connected to a numerical indicator of the index you need.

    Before we can use the 'Get At' function, we need to sort the "member" items on their join dates.

    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, notice as you do this its output connection point is created and mirrors the input "member" data.

    Now the Sort Values output contains the "member" items for a "club" sorted according to join date.

    Connecting the output from the "Sort" to the 'Nodes' input on the "Get At" will cause the output connection point on the "Get At" to be created (see Dynamic Output Values).

    The "Get At" output should be connected to the "player" connection point on the XML Writer.

    Reader to Sort

     

    Now we need to represent the second position within the sorted sequence, since we want the second earliest "member" item. Drag a Constant Value from the Data Type section onto the Mapper and right-click it, choosing Show Properties. Enter an integer type from the Data Type drop-down list and the number 1 as the Value, since we are working with a zero-based index, so the second position is at index 1.

    Constant Properties

    Connect the Constant output to the Index input in the Get At function.

    Now we can connect the Get At output 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.

    Input and Output Connections Mapped

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

    Output XML
    Copy Code
    <clubs>
     <team t_name="New Town Football Club">
      <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="Joanne Smith" is_active="Yes">
       <joined>2005</joined>
       <title>Regional Championship 2007</title>
       <title>National championship 2007</title>
      </player>
     </team>
    </clubs>
    

    Each "team" element only contains a single "player" element - the "player" with the second earliest "joined" value from the source. Since the Get At function takes a numerical input representing the index value you are interested in, this input can come from a variety of other sources. Although we used a Constant to represent it here, you may need to determine the index you require using other functions, such as those from the Maths and Aggregate sections.

    In order to use the Get At function successfully, you should make sure you only feed it index values that are actually within the range of values in your source data.
    See Also