Data Map or Lookup resources contain mappings which can be applied to incoming data records to enhance attribute values. For example, a mapping might convert an integer event code into a string description.
Data maps may be statically created with a mapping expressed in JSON passed in the request body of methods to create lookup. Dynamically-updated lookups are supported by creating a data destination with type data_map, associated with a corresponding data set that defines the map. For details on creating dynamic lookups, see the Data Destination section.
To include lookup entry counts and caching information, include the validate=1 query parameter in your GET request.
By default, GET calls to /data_maps do not show the content of the mapping itself, as those tend to be large arrays of objects.
Use the endpoint below to create a new lookup. Lookups require a name. For statically assigned lookups, pass data_defaults as an object and data_map as an array of objects. You must include map_primary_key to specify which map attribute should be used for data matching:
Lookups are private to the creating account and collaborators by default. A private lookup can't be read in full with a GET request by users without access privileges, but the lookup is applied in any data set transformation where it is specified, regardless of the map's visibility to potential sharers.
The response to a successful POST request to /data_maps contains the metadata for the lookup that was created.
To create a dynamic lookup, include a valid data destination id in the data_sink_id attribute of the POST request body.
The mapping for a dynamic lookup is automatically generated when data is written to the data destination. The data_map attribute of a dynamic data cannot explicitly be set with either POST or PUT requests.
Issue a PUT request to the /data_maps/<data_map_id> endpoint to update the metadata of a lookup resource. If the data map is static, you may also update the mapping itself by including the data_map attribute in your request object.
Note The PUT request only supports updating the entire mapping of a static lookup. To manage specific mapping entries, use the /data_maps/<data_map_id>/entries endpoints documented in the following section.
Use the endpoint below to list specific data map entries without downloading the entire mapping. The response contains a list of map entries having primary key values matching entry_key path component.
Include a comma-separated list of entry keys to retrieve multiple entries.
List Lookup Entries: Request
Example Request Payload: 1
Example Request Payload: 2
List Lookup Entries: Response
The entry_key path component may contain a simple matching expression with * wildcard characters. The response will contain entries whose primary key value matches the wildcard pattern.
To update or add specific mapping entries without replacing the entire data map, issue a PUT request to the /data_maps/<data_map_id>/entries endpoint with a list of map entry objects in the entries attribute of the request body.
Note: This endpoint supports updating entries on dynamic lookups, but any entries added or updated this way could be overwritten as a result of data written to the map's data destination. Use with caution.
The PUT response contains a list of entries that were successfully set in the lookup.
While the methods allowing searching for lookup entries empower you to check whether the lookup contains specific entries or not, you can also fetch a batch of samples from the lookup by calling the method below. Set the field name and pagination info to fetch samples matching the filter criteria.
View Sample Lookup Entries: Request