How can we help?

MAPFLAT and MAP

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

MAP( values, variable name, expression)

MAPFLAT( values, variable name, expression)

The MAP function is used to repeat a formula over a set of values. It assigns values specified by the first parameter to variable name, one at a time, 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. For instructions on creating variables, see Variables.

The MAP function returns a single value for each of the values provided in the first parameter.

The MAPFLAT function returns an set of values for each of the values provided in the first parameter.

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.

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.

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:

Advanced Uses

The MAP function is particularly useful when working with dynamic data sources and XML/JSON 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:

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; )))

The following MAPFLAT function returns the sessions for each country, SLICE( @B:B; ), for each dynamic data source instance created by setting gaID to gaID1, gaID2 and gaID3

MAPFLAT( ARRAY( "gaID1", "gaID2", "gaID3"), "gaID", 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.

Examples

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.

Where FacebookDSid is the data source ID of a JSON format Facebook data source, the DATASOURCE function is used to return the name of an individual object, in this example, data/values[1]/value[1]/*[1].

DATASOURCE( FacebookDSid, "name(/data/values[1]/value[1]/*[1])" )

returns: F.13-17

Use the MAP function to return the names of all objects in the array, data/values[1]/value[1]/*.