Skip to main content

Update a Lookup

Updating lookups in Nexla allows you to modify lookup configurations, content, and metadata to reflect changing business requirements and data structures. The update process supports both metadata changes and content modifications for static lookups.

Update Capabilities​

The lookup update functionality provides comprehensive control over lookup resources:

  • Metadata Updates: Modify lookup names, descriptions, and configuration parameters
  • Content Updates: Update lookup entries and data for static lookups
  • Access Control: Modify ownership, organization, and visibility settings
  • Configuration Changes: Update lookup behavior and performance settings

Update Endpoint​

To update an existing lookup, use the following endpoint:

PUT /data_maps/{data_map_id}

Update Types​

The lookup update functionality supports several different types of modifications, each designed for specific use cases and requirements. Understanding these update types helps you choose the most appropriate approach for your specific needs and ensures efficient lookup management.

Metadata Updates​

Update basic lookup information and configuration:

Update Lookup Metadata: Request
PUT /data_maps/1001

{
  "name": "Updated Event Code Lookup",
  "description": "Enhanced event code mapping with additional categories",
  "emit_data_default": true,
  "use_versioning": true
}

Content Updates​

For static lookups, you can update the entire mapping content:

Update Lookup Content: Request
PUT /data_maps/1001

{
  "name": "Enhanced Event Code Lookup",
  "data_map": [
    {
      "eventId": "0",
      "description": "Search Event",
      "category": "Web Activity",
      "priority": "Low"
    },
    {
      "eventId": "1",
      "description": "Checkout Event",
      "category": "E-commerce",
      "priority": "High"
    },
    {
      "eventId": "2",
      "description": "Return Event",
      "category": "E-commerce",
      "priority": "Medium"
    },
    {
      "eventId": "3",
      "description": "Login Event",
      "category": "Authentication",
      "priority": "Medium"
    }
  ]
}

Ownership and Organization Updates​

Update lookup ownership and organization settings:

Update Ownership: Request
PUT /data_maps/1001

{
  "owner_id": 43,
  "org_id": 102
}

Update Considerations​

When updating lookups, it's important to understand the different constraints and behaviors that apply to various update scenarios. These considerations help ensure successful updates and prevent unintended consequences that could affect lookup functionality or data integrity.

Static vs. Dynamic Lookups​

  • Static Lookups: Support full content updates through the data_map attribute
  • Dynamic Lookups: Content updates are limited as they are managed by data flows
  • Hybrid Updates: Some fields can be updated regardless of lookup type

Content Update Limitations​

The PUT request only supports updating the entire mapping of a static lookup. To manage specific mapping entries, use the dedicated entries endpoints:

  • Individual Entry Updates: Use /data_maps/{data_map_id}/entries endpoint
  • Bulk Entry Operations: Support for adding, updating, and removing specific entries
  • Selective Modifications: Modify only the entries that need changes

Update Response​

A successful update returns the updated lookup object with all current configuration details and metadata. The response includes the complete updated lookup structure, allowing you to verify that your changes were applied correctly.

Update Lookup Response: Example
{
  "id": 1001,
  "owner": {
    "id": 42,
    "full_name": "John Smith"
  },
  "org": {
    "id": 101,
    "name": "Acme Corporation",
    "email_domain": "acme.com"
  },
  "access_roles": ["owner"],
  "name": "Enhanced Event Code Lookup",
  "description": "Enhanced event code mapping with additional categories and priority levels",
  "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": true,
  "map_primary_key": "eventId",
  "data_defaults": {
    "eventId": "Unknown",
    "description": "Unknown Event",
    "category": "Unknown Category",
    "priority": "Unknown"
  },
  "map_entry_schema": {
    "properties": {
      "category": {
        "type": "string"
      },
      "description": {
        "type": "string"
      },
      "eventId": {
        "format": "integer",
        "type": "string"
      },
      "priority": {
        "type": "string"
      }
    },
    "type": "object",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$schema-id": 2098320124
  },
  "updated_at": "2023-01-15T19:45:30.000Z",
  "created_at": "2023-01-15T15:47:16.000Z",
  "tags": []
}

Best Practices​

To effectively update lookups:

  1. Backup Before Updates: Ensure you have a backup of current lookup content
  2. Test Updates: Validate updates in a non-production environment first
  3. Incremental Changes: Make small, focused updates rather than large changes
  4. Document Changes: Keep records of what was updated and why
  5. Verify Results: Confirm that updates produce the expected results

Error Handling​

Common update issues and solutions:

  • Invalid Content Structure: Ensure updated content matches the expected schema
  • Permission Issues: Verify you have update permissions for the lookup
  • Content Conflicts: Check for conflicts between static and dynamic content
  • Schema Mismatches: Ensure updated content conforms to the lookup schema

After updating lookups, you may need to:

Verify Updates​

GET /data_maps/{lookup_id}

Test Functionality​

GET /data_maps/{lookup_id}/entries/{entry_key}

Manage Individual Entries​

PUT /data_maps/{lookup_id}/entries
DELETE /data_maps/{lookup_id}/entries/{entry_key}

Download Updated Content​

GET /data_maps/{lookup_id}/download_map