Map data type

The data type Map<> associates a set of keys to values. Each map object can contain one or more items, and each item in the object is a key-value pair. In TDE, the key is always of type Text, and the value can be any of the TDEdata types.

In the table documentation, columns of this type list the Map data type in addition to the key and value data types. For example, the Point table's Dtcs column has a data type of Map<Text, Array<Text>>. For each item in a Dtcs map object, the key is text, and the value is an array of text.

Usage

Retrieving maps

When retrieving a map object, you can either retrieve the full object or individual items within the object by key. You can retrieve individual map items in any Format. However, retrieving the full map object requires the following settings in the [Template] section of your template:

The StructuredData entry must be set to true, so that map data is output in a standard structure.
The Format entry must be set to either XPath or JSON.

The Retrieve template below shows how to retrieve a map and an item within a map.

Retrieve template

Copy

[Template]
TemplateVersion = 1.0
TableID = Point-2.0
TemplateName = RetrievePoint
Intent = Retrieve
Format = Json
ElementName = Points
StructuredData = True

[Output]
UnitId = Input.UnitId
AllDTCs = Input.Dtcs                  # Retrieves the map object
OBDII_DTCs = Input.Dtcs["OBDII_DTC"]  # Retrieves a single item in the map object by key: ["OBDII_DTC"]

[Calculated]
ReportStart(Timestamp) = "10/23/2014 4:48:00 PM"
ReportEnd(Timestamp) = "2014/10/24"

[Filter]
Time = Between(ReportStart, ReportEnd)

In the sample output shown below, AllDTCs is the full map object, and it contains three items. OBDII_DTCs is a single item retrieved from within the Dtcs map object by key, and it contains three values.

Retrieve output

Copy

{
  "RetrievePoint": {
    "Points": [
      {
        "OBDII_DTCs": [
            "OBDII 345",
            "OBDII 456",
            "OBDII 567"
          ],
        "UnitId": "463673",
        "AllDTCs": {
          "J1587_DTC": [
            "J1587 234",
            "J1587 987"
          ],
          "OBDII_DTC": [
            "OBDII 345",
            "OBDII 456",
            "OBDII 567"
          ],
          "J1939_DTC": [
            "J1939 678",
            "J1939 789"
          ]
        }
      }
    ]
  }
}

Creating and updating maps

Insert each map item by key to create or update a map. The structure of the data you input for the map must match the type signature of the map object, which is provided in the table documentation for any columns that have the map data type.

For example, in the Create template below, three items are inserted for the Dtcs map object. Its data type is Map<Text, Array<Text>>. To insert data that matches the type signature for this column, each of the Dtcs map items in the input file contains an array of text.

Create template

Copy

[Template]
TemplateVersion = 2.0
TableID = Point-2.0
TemplateName = CreatePoint
Intent = Create
Format = Json
ElementName = Points

[Output]
Time = Input.Time
UnitId(UnitId) = Input.UnitId
UnitType = Input.UnitType
GpsQuality = Input.GpsQuality
Lat(Degree) = Input.Lat
Lon(Degree) = Input.Lon
Ignition = Input.Ignition
"Dtcs" = Input.Dtcs  # Inserts values into the Dtcs map for the ["OBDII_DTC"] key

The input data for the Create template example above:

JSON input

Copy

{
  "Points": [
        {
          "Time": "10/23/2014 4:48:00 PM",
          "UnitId": "1",
          "UnitType": "W",
          "GpsQuality": "Excellent",
          "Lat": "12.3399995172024",
          "Lon": "-43.2099995440244",
          "Ignition": "true",
          "dtcs": {
             "OBDII_DTC": ["123", "234", "345"],
             "J1587_DTC": ["456", "567", "678"],
             "J1939_DTC": ["89", "98"]
            }
        }
  ]
}

JavaScript conversion

When you use the optional [Script] section to insert your own JavaScript functions, you can work with a Map<> item much like you would work with JavaScript object properties.

Creation

JavaScript

Copy

var myMap = {};

This example shows how to create a new Map object and set keys to different values.

JavaScript

Copy

var myMap = {};
myMap[“Key1”] = 15;
myMap[“Key2”] = “Foo”;
row.myField = myMap;