MergeLists 1.0.0¶

Overview¶

Function Beginner

Description¶

⚠️ Deprecated: This block is obsolete. Use the "Join" block instead for advanced join operations.

Merges objects from two lists by matching on the configured key. Performs an outer join operation, combining objects that share the same key value and including all unique objects from both lists.

Configuration Options¶

Name	Data Type	Description	Default Value
key	`str`	Field name to use for matching objects between the two lists. Must exist in all objects from both lists	Required

Inputs¶

Name	Data Type	Description
a	`list[dict[str, Any]]`	First list of dictionary objects to merge. Each object must contain the configured key field
b	`list[dict[str, Any]]`	Second list of dictionary objects to merge. Each object must contain the configured key field

Outputs¶

Name	Data Type	Description
result	`list[dict[str, Any]]`	Merged list containing all unique objects. Objects with matching keys are combined, with list 'b' properties overriding list 'a' properties

Examples¶

blocks:
  - name: merge_customer_data
    type: MergeLists
    config:
      key: "customer_id"
    input:
      a:
        - customer_id: "cust_001"
          name: "John Doe"
          email: "john@example.com"
        - customer_id: "cust_002"
          name: "Jane Smith"
          email: "jane@example.com"
      b:
        - customer_id: "cust_001"
          phone: "555-0123"
          status: "active"
        - customer_id: "cust_003"
          name: "Bob Wilson"
          email: "bob@example.com"

# Output (outer join result):
# [
#   {"customer_id": "cust_001", "name": "John Doe", "email": "john@example.com", "phone": "555-0123", "status": "active"},
#   {"customer_id": "cust_002", "name": "Jane Smith", "email": "jane@example.com"},
#   {"customer_id": "cust_003", "name": "Bob Wilson", "email": "bob@example.com"}
# ]

blocks:
  - name: merge_with_overrides
    type: MergeLists
    config:
      key: "product_id"
    input:
      a:
        - product_id: "prod_001"
          name: "Laptop"
          price: 999.99
          category: "Electronics"
        - product_id: "prod_002"
          name: "Mouse"
          price: 29.99
      b:
        - product_id: "prod_001"
          price: 899.99  # This will override the price from list 'a'
          discount: 0.10
          availability: "in_stock"

# Output (list 'b' properties override list 'a'):
# [
#   {
#     "product_id": "prod_001",
#     "name": "Laptop",
#     "price": 899.99,        # Overridden by list 'b'
#     "category": "Electronics",
#     "discount": 0.10,       # Added from list 'b'
#     "availability": "in_stock"
#   },
#   {
#     "product_id": "prod_002",
#     "name": "Mouse",
#     "price": 29.99
#   }
# ]

# DEPRECATED - MergeLists usage
blocks:
  - name: old_merge_approach
    type: MergeLists  # ⚠️ Obsolete
    config:
      key: "id"

# RECOMMENDED - Use Join block instead
blocks:
  - name: new_join_approach
    type: Join
    config:
      key: "id"
      joinType: "OUTER"  # Equivalent to MergeLists behavior
    input:
      left: # First list (equivalent to 'a')
        - id: "item_1"
          name: "First Item"
      right: # Second list (equivalent to 'b')  
        - id: "item_1"
          status: "active"

# The Join block provides:
# - Multiple join types (INNER, OUTER, LEFT_INNER, LEFT_OUTER, RIGHT_INNER, RIGHT_OUTER)
# - Better error handling
# - More explicit behavior
# - Enhanced performance

Error Handling¶

Key Not Found Error

Error Code: KeyError
Common Cause: One or more objects in either list do not contain the configured key field
Solution: Ensure all objects in both lists contain the specified key field, or filter out objects missing the key before merging

Type Error

Error Code: TypeError
Common Cause: Input lists contain non-dictionary objects or key values are not hashable
Solution: Verify that both inputs are lists of dictionaries and that key values are hashable types (strings, numbers, etc.)

Deprecation Warning

Error Code: DeprecationWarning
Common Cause: Using obsolete MergeLists block instead of recommended Join block
Solution: Migrate to the Join block with joinType set to "OUTER" for equivalent functionality with better performance and features

FAQ¶

Why is this block marked as obsolete?

MergeLists has been superseded by the Join block which provides more join types, better error handling, and clearer semantics. The Join block with joinType="OUTER" provides identical functionality to MergeLists.

How do I migrate from MergeLists to Join?

Replace MergeLists with Join, change input parameters from 'a' and 'b' to 'left' and 'right', and set joinType to "OUTER". The key configuration remains the same and the output behavior is identical.

What type of join operation does MergeLists perform?

MergeLists performs an outer join operation, including all objects from both lists. Objects with matching key values are merged together, while unique objects appear unchanged in the result.

How are conflicting properties handled during merging?

When objects with the same key contain conflicting property names, the values from list 'b' override those from list 'a'. This follows Python's dictionary update semantics where the later value wins.

Can I still use MergeLists in new projects?

While MergeLists still functions, it's not recommended for new projects. Use the Join block instead for better maintainability, performance, and access to additional join types that may be useful as your requirements evolve.