Lookups / Data Maps

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.

List All Lookups

Both Nexla API and Nexla CLI support methods to list all lookups in the authenticated user's account.

Nexla API
Nexla CLI

List All Lookups: Request
GET /data_maps

List All Lookups: Request

nexla lookup list

Nexla API
Nexla CLI

List All Lookups: Response
[
  {
    "id": 1001,
    "owner": {
      "id": 2,
      "full_name": "Jeffrey Williams",
      "email": "jcw@nexla.com"
    },
    "org": {
      "id": 1,
      "name": "Nexla",
      "email_domain": "nexla.com",
      "email": null
    },
    "access_roles": ["owner"],
    "name": "Example simple key/value map",
    "description": null,
    "public_map": true,
    "managed": false,
    "data_type": "string",
    "data_format": null,
    "data_sink_id": null,
    "data_set_id": null,
    "emit_data_default": true,
    "use_versioning": false,
    "map_primary_key": "key",
    "data_defaults": {
      "key": "unknown",
      "value": "Unknown value"
    },
    "map_entry_schema": {
      "properties": {
        "key": {
          "format": "integer",
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      },
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "$schema-id": 2098320124
    },
    "updated_at": "2019-05-02T17:42:38.000Z",
    "created_at": "2017-05-31T15:47:16.000Z",
    "tags": []
  },
  {
    "id": 1016,
    "owner": {
      "id": 2,
      "full_name": "Jeffrey Williams",
      "email": "jcw@nexla.com"
    },
    "org": {
      "id": 1,
      "name": "Nexla",
      "email_domain": "nexla.com",
      "email": null
    },
    "access_roles": ["owner"],
    "name": "Dep Code to Brand",
    "description": null,
    "public_map": false,
    "managed": false,
    "data_type": "string",
    "data_format": null,
    "data_sink_id": 5014,
    "data_set_id": null,
    "emit_data_default": true,
    "use_versioning": false,
    "map_primary_key": "departmentCode",
    "data_defaults": {
      "departmentCode": "0",
      "brand": ""
    },
    "map_entry_schema": null,
    "updated_at": "2017-07-31T23:16:49.000Z",
    "created_at": "2017-07-31T23:16:49.000Z",
    "tags": []
  },
  {
    "id": 1022,
    "owner": {
      "id": 2,
      "full_name": "Jeffrey Williams",
      "email": "jcw@nexla.com"
    },
    "org": {
      "id": 1,
      "name": "Nexla",
      "email_domain": "nexla.com",
      "email": null
    },
    "access_roles": ["owner"],
    "name": "Example static multi-value map",
    "description": "Order Items",
    "public_map": false,
    "managed": false,
    "data_type": "string",
    "data_format": null,
    "data_sink_id": null,
    "data_set_id": null,
    "emit_data_default": true,
    "use_versioning": false,
    "map_primary_key": "key",
    "data_defaults": {},
    "map_entry_schema": {
      "properties": {
        "ItemNo": {
          "format": "integer",
          "type": "string"
        },
        "OrderNo": {
          "format": "integer",
          "type": "string"
        },
        "Price": {
          "format": "number",
          "type": "string"
        },
        "Qty": {
          "format": "integer",
          "type": "string"
        },
        "key": {
          "type": "string"
        }
      },
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "$schema-id": 591610723
    },
    "updated_at": "2019-05-02T17:38:05.000Z",
    "created_at": "2018-06-28T23:04:28.000Z",
    "tags": []
  }
]

List All Lookups: Response
  id       name
----      ------------------------------------
1023       test_lookup
1024       test1_lookup

Show A Lookup

Fetch a specific lookup accessible to the authenticated user.

Nexla API
Nexla CLI

Show One Lookup: Request
GET /data_maps/{data_map_id}

Show One Lookup: Request
nexla lookup get <lookup_id>

Nexla API
Nexla CLI

Show One Lookup: Response
{
  "id": 1001,
  "owner": {
    "id": 2,
    "full_name": "Jeffrey Williams",
    "email": "jcw@nexla.com"
  },
  "org": {
    "id": 1,
    "name": "Nexla",
    "email_domain": "nexla.com",
    "email": null
  },
  "access_roles": ["owner"],
  "name": "Example simple key/value map",
  "description": null,
  "public_map": true,
  "managed": false,
  "data_type": "string",
  "data_format": null,
  "data_sink_id": null,
  "data_set_id": null,
  "emit_data_default": true,
  "use_versioning": false,
  "map_primary_key": "key",
  "data_defaults": {
    "key": "unknown",
    "value": "Unknown value"
  },
  "map_entry_schema": {
    "properties": {
      "key": {
        "format": "integer",
        "type": "string"
      },
      "value": {
        "type": "string"
      }
    },
    "type": "object",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$schema-id": 2098320124
  },
  "updated_at": "2019-05-02T17:42:38.000Z",
  "created_at": "2017-05-31T15:47:16.000Z",
  "tags": []
}

Show One Lookup: Response
{
    "data_defaults": {},
    "name": "test",
    "data_type": "string",
    "data_map": [],
    "map_primary_key": "product_id",
    "description": null
}

List and Show Options

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.

Nexla API

List & Show Options: Request
GET /data_maps?validate=1

GET /data_maps/{data_map_id}?validate=1

Nexla API

List & Show Options: Response
{
  "id": 1001,
  "owner": {
    "id": 2,
    "full_name": "Jeffrey Williams",
    "email": "jcw@nexla.com"
  },
  "org": {
    "id": 1,
    "name": "Nexla",
    "email_domain": "nexla.com",
    "email": null
  },
  "access_roles": ["owner"],
  "name": "Example simple key/value map 2",
  "description": null,
  "public_map": true,
  "managed": false,
  "data_type": "string",
  "data_format": null,
  "data_sink_id": null,
  "data_set_id": null,
  "emit_data_default": true,
  "use_versioning": false,
  "map_primary_key": "key",
  "data_defaults": {
    "key": "unknown",
    "value": "Unknown value"
  },
  "map_entry_info": {
    "cached": true,
    "cached_entry_count": 10,
    "static_entry_count": 10
  },
  "map_entry_schema": {
    "properties": {
      "key": {
        "format": "integer",
        "type": "string"
      },
      "value": {
        "type": "string"
      }
    },
    "type": "object",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$schema-id": 2098320124
  },
  "updated_at": "2019-05-02T17:42:38.000Z",
  "created_at": "2017-05-31T15:47:16.000Z",
  "tags": []
}

Create a Static Lookup

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.

Nexla API

Create A Lookup: Request
POST /data_maps
...
Example Request Payload
{
  "name": "Example Data Map 2",
  "data_type" : "string",
  "emit_data_default" : true,
  "map_primary_key" : "eventId",
  "data_defaults" : {
    "eventId" : "Unknown",
    "description" : "Unknown",
    "category" : "Unknown"
  },
  "data_map" : [
    {
      "eventId" : "0",
      "description" : "Search",
      "category" : "Web"
    },
    {
      "eventId" : "1",
      "description" : "Checkout",
      "category" : "App"
    },
    {
      "eventId" : "2",
      "description" : "Return",
      "category" : "App"
    }
  ]
}

Nexla API

Create A Lookup: Response
{
  "id": 1023,
  "owner": {
    "id": 2,
    "full_name": "Jeffrey Williams",
    "email": "jcw@nexla.com"
  },
  "org": {
    "id": 1,
    "name": "Nexla",
    "email_domain": "nexla.com",
    "email": null
  },
  "access_roles": ["owner"],
  "name": "Example Data Map, simple multi-value",
  "description": null,
  "public_map": false,
  "managed": false,
  "data_type": "string",
  "data_format": null,
  "data_sink_id": null,
  "data_set_id": null,
  "emit_data_default": true,
  "use_versioning": false,
  "map_primary_key": "eventId",
  "data_defaults": {
    "eventId": "Unknown",
    "description": "Unknown",
    "category": "Unknown"
  },
  "map_entry_schema": {
    "properties": {
      "category": {
        "type": "string"
      },
      "description": {
        "type": "string"
      },
      "eventId": {
        "format": "integer",
        "type": "string"
      }
    },
    "type": "object",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$schema-id": 169361033
  },
  "updated_at": "2019-05-02T18:32:10.567Z",
  "created_at": "2019-05-02T18:32:10.567Z",
  "tags": []
}

Create A Dynamic Lookup

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.

Update a Lookup

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.

Search for Lookup Entries

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.

[
  {
    "OrderNo": "1001",
    "Price": "3.02",
    "key": "1001_1",
    "ItemNo": "1",
    "Qty": "111"
  }
]

Include a comma-separated list of entry keys to retrieve multiple entries.

Nexla API

List Lookup Entries: Request
GET /data_maps/{data_map_id}/entries/{entry_key}[,{entry_key}...]
...
Example Request Payload: 1
GET /data_maps/1022/entries/1001_1
...
Example Request Payload: 2
GET /data_maps/1022/entries/1001_1,1002_1

Nexla API

List Lookup Entries: Response
[
  {
    "OrderNo": "1001",
    "Price": "3.02",
    "key": "1001_1",
    "ItemNo": "1",
    "Qty": "111"
  },
  {
    "OrderNo": "1002",
    "Price": "4.38",
    "key": "1002_1",
    "Qty": "100",
    "ItemNo": "1"
  }
]

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.

Nexla API

List Lookup Entries With Wildcard: Request
...Example Request
GET /data_maps/1022/entries/1001_*,*_4

Nexla API

List Lookup Entries With Wildcard: Response
[
  {
    "OrderNo": "1001",
    "Price": "3.02",
    "key": "1001_1",
    "ItemNo": "1",
    "Qty": "111"
  },
  {
    "OrderNo": "1001",
    "Price": "34.25",
    "key": "1001_3",
    "ItemNo": "3",
    "Qty": "21"
  },
  {
    "OrderNo": "1001",
    "Price": "31",
    "key": "1001_2",
    "ItemNo": "2",
    "Qty": "788"
  },
  {
    "OrderNo": "1002",
    "Price": "40.38",
    "key": "1002_4",
    "ItemNo": "4",
    "Qty": "10000"
  }
]

Set Lookup Entries

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.

Nexla API

Set Lookup Entries: Request
PUT /data_maps/{data_map_id}/entries

Nexla API

Set Lookup Entries: Response
{
  "entries": [
    {
      "OrderNo": "1002",
      "Price": "40.38",
      "key": "1002_4",
      "ItemNo": "4",
      "Qty": "10000"
    },
    {
      "OrderNo": "1002",
      "Price": "4.38",
      "key": "1002_1",
      "ItemNo": "1",
      "Qty": "100"
    }
  ]
}

Delete Lookup Entries

To delete specific mapping entries without replacing the entire lookup, issue a DELETE request to the /data_maps/<data_map_id>/entries/<entry_key> endpoint.

Nexla API

Delete Lookup Entries: Request
GET /data_maps/{data_map_id}/entries/{entry_key}[,{entry_key}...]
...
Example Request: 1
DELETE /data_maps/1022/entries/1001_1,1001_2

Nexla API

Delete Lookup Entries: Response
The DELETE response is HTTP 200 and an empty body, unless the data map is invalid.

Note This endpoint supports deleting entries from dynamic lookups, but any entries removed this way could be re-added as a result of data written to the lookup's data destination. Use with caution.

Wildcards cards are not supported in the entries keys passed in DELETE requests.

Download Lookup Entries

Use the method below to download the lookup content in csv format for a given data_map_id.

Nexla API

Download Lookup Entries: Request
GET /data_maps/<data_map_id>/download_map

Nexla API

Download Lookup Entries: Response
key,value,
2,two,

View Sample Lookup Entries

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.

Nexla API

View Sample Lookup Entries: Request
POST /data_maps/<data_map_id>/probe/sample?page=1&per_page=10
...
Request Payload:
{
  "id.field.name": "*" or field name
}

Nexla API

View Sample Lookup Entries: Response
{
  "status": 200,
  "message": "Ok",
  "output": {
    "response": "{\"last_name\":\"Montoya\",\"id\":\"122\",\"balance\":\"63789\",\"first_name\":\"Laith\",\"age\":\"53\",\"email\":\"varius.orci@arcu.com\",\"join_date\":\"891568916000\"}\n{\"last_name\":\"Roberson\",\"id\":\"104\",\"balance\":\"50849\",\"first_name\":\"Penelope\",\"age\":\"85\",\"join_date\":\"1516996039000\",\"email\":\"ante@vitaedolor.co.uk\"}",
    "statusCode": 200,
    "contentType": "application/json"
  }
}

List All Lookups​

Show A Lookup​

List and Show Options​

Create a Static Lookup​

Create A Dynamic Lookup​

Update a Lookup​

Search for Lookup Entries​

Set Lookup Entries​

Delete Lookup Entries​

Download Lookup Entries​

View Sample Lookup Entries​