MAP function

Using the map function

This article describes basic MAP functionality and also advanced usage with dynamic and XML/JSON data sources.

MAP( values, variable name, expression)

The MAP function is used to repeat a formula over a set of values. It assigns, one at a time, values specified by the first parameter to variable name and for each value, executes the formula specified by expression. Note that the second parameter, variable name, must be entered as a literal string (without quotes) while the variable used in expression is entered as a variable, (x). For instructions on creating variables, see Variables.

Example 1


The following example assigns each item in ARRAY( apples, blueberries, pears ) to the variable, fruit, then sums all items in column C where the corresponding item in column A = fruit.




MAP( ARRAY( apples, blueberries, pears ),
         fruit,
         SUM( SELECT( C:C, 
A:A = fruit  ) ) )

returns  (33, 42, 35)

Example 2


The MAP function can be used to retrieve data with a many-to-many relationship. For example, a garden can have many flowers and a flower may be planted in many gardens. Using the following data source:




LOOKUP( A:A, C:C, LOOKUP( B:B, D:D, E:E ) ) returns only the colour of the first flower found for each garden in column A: ( red, red, purple, purple, blue )

The MAP function can be used to return all the flower colours in each garden. Note the use of the JOIN function to combine results into comma-separated values.

MAP( A:A, var, JOIN( LOOKUP( SELECT( B:B, (C:C = var) ), D:D, E:E ) ) )

returns ( red,blue,pink
               red,purple,blue
               purple,blue,pink
               purple,blue
               blue,yellow,pink )

Notes

  • The first parameter, values, must not be null otherwise the function will return an error. For example, the following formula will return an error because the first SELECT returns 0 items.
  •      
    MAP( SELECT( 
    ARRAY( apples, blueberries, pears ), ( ARRAY( apples, blueberries, pears ) = bananas) ),
                   fruit,
                   SUM( SELECT( C:C, 
    A:A = fruit ) ) )  returns  (33, 42, 35)

    To work around this, check the number of items returned by the SELECT before executing the MAP function:

         IF( COUNT( 
    SELECT( ARRAY( apples, blueberries, pears ), ( ARRAY( apples, blueberries, pears ) = bananas) ) ) > 0,
              MAP( SELECT( ARRAY( apples, blueberries, pears ), ( ARRAY( apples, blueberries, pears ) = bananas) ),
              fruit, 
              SUM( SELECT( C:C, 
    A:A = fruit ) ) ),
     0 )

  • The MAP function returns only one value for each expression result. If expression returns an array of values, only the first item in the array is returned by the MAP function. To return the entire array of expression results for each instance of variable name, you must wrap the JOIN function around expression, to combine the results into a single, comma-separated value. For example, using the following data source:

The formula

     MAP( ARRAY( apples, blueberries, pears ), fruit, SELECT( SLICE( B:B ), ( SLICE( A:A ) = fruit ) ) ) 

returns ( 
British Columbia
              Manitoba
              British Columbia )

while the formula 

     MAP( ARRAY( apples, blueberries, pears ), fruit, JOIN( SELECT( SLICE( B:B ), ( SLICE( A:A ) = fruit ) ) ) )

returns ( British Columbia,Ontario,Nova Scotia
              Manitoba,Prince Edward Island,Saskatchewan
              British Columbia,Ontario )

Advanced Uses


The MAP function is particularly useful when working with dynamic data sources and JSON/XML data sources.

Dynamic Data Sources


The MAP function can be used to repeat a formula for a set of dynamic data source instances, where the variable specified in the MAP function is the variable used to create the dynamic data source (for more information, see Dynamic Data Sources).

The following example uses a Google Analytics dynamic data source that uses the variable, gaID, for the Profile ID:

https://www.googleapis.com/analytics/v3/data/ga?ids=ga:{props.gaID}&dimensions=ga:country&metrics=ga:sessions&start-date={date.add(-30).format()}&end-date={date.today}&max-results=10000

and returns data in the following format:


The following MAP function returns the total number of sessions, SUM( SLICE( B:B ) ), for each dynamic data source instance created by setting gaID to gaID1, gaID2 and gaID3:

MAP( ARRAY( gaID1, gaID2, gaID3), gaID, SUM( SLICE( B:B )  ) )  

JSON/XML Data Sources


JSON and XML data sources can require special handling to access their arrays and objects. This typically involves editing the XPath to traverse the data hierarchy. In this scenario, the DATASOURCE function can be useful.

Example

Where LinkedInDsid is the data source ID of a LinkedIn data source, the following retrieves the last name of all connections with first-name = Dave.

DATASOURCE( LinkedInDSid, /connections/person[first-name='Dave']/last-name ] ) 

This formula can be made more flexible by using the MAP and CONCAT functions. Note the use of the JOIN function to
combine results into comma-separated values.

     MAP( ARRAY( Dave, Mary ),
              name,
              JOIN( DATASOURCE( LinkedInDSid,
                                                  CONCAT( /connections/person[first-name=', name ']/last-name ] ) ) )

Related links:

Functions

  1. Introduction: Using formulas
  2. Data Manipulation functions
  3. Logic functions
  4. Math functions
  5. SELECT function
  6. Text Functions
  7. Date and Time Functions
  8. Statistics Functions
  9. ABS function
  10. AND function
  11. ARRAY function
  12. AVERAGE function
  13. BETWEEN function
  14. BLANK function
  15. CAPITALIZE function
  16. CEILING function
  17. CONCAT function
  18. CONTAINS function
  19. COUNT function
  20. COUNTALL function
  21. COUNTBLANK function
  22. COUNTDISTINCT function
  23. COUNTIF function
  24. COUNT_DAYS function
  25. COUNTNUMERIC function
  26. CUMULATIVE function
  27. CUMULATIVE_DIFFERENCE function
  28. DATASOURCE function
  29. DATE and DATEVALUE functions
  30. Using Date and Time Formats
  31. DATERANGE function
  32. DATE_ADD function
  33. DATE_CLOSEST function
  34. DATE_CONVERT function
  35. DATE_ENDOF function
  36. DATE_IN function
  37. DATE_SET function
  38. DATE_STARTOF function
  39. DATE_UNITVALUE function
  40. FLOOR function
  41. ERF function
  42. FIRST function
  43. ERFC function
  44. GROUP and GROUPBY functions
  45. IF function
  46. IN function
  47. INDEXOF function
  48. JOIN function
  49. LAST function
  50. LASTINDEXOF function
  51. LEFT function
  52. LOOKUP function
  53. LOWER function
  54. MAP function
  55. MAX function
  56. MIN function
  57. MEDIAN function
  58. MOD function
  59. MODE function
  60. Moving Average (Cumulative)
  61. Moving Average (Exponential)
  62. Moving Average (Simple)
  63. NORMSDIST function
  64. NOT function
  65. NOW function
  66. NUMBERFORMAT function
  67. OR function
  68. PADVALUES function
  69. POWER function
  70. RANK function
  71. REMOVE_EMOJI function
  72. REPEAT function
  73. REPLACE function
  74. REVERSE function
  75. RIGHT function
  76. ROUND function
  77. SET function
  78. SLICE function
  79. SLOPE function
  80. SORT function
  81. SPLICE function
  82. STANDARDIZE function
  83. STDEV function
  84. STDEVP function
  85. SUBSTITUTE function
  86. SUBSTITUTE_REGEX function
  87. SUBSTRING function
  88. SUM function
  89. SUMIF function
  90. SWITCH function
  91. TEXT_REVERSE function
  92. TODAY function
  93. TRIM function
  94. TRUNCATE function
  95. UPPER function
  96. URLDECODE function
  97. URLENCODE function
  98. VARIANCE function
  99. VARIANCEP function
  100. YESTERDAY function
  101. ZTEST function

Feedback and Knowledge Base