Go to Studio

Join List

Join two lists of objects on matching properties (like SQL JOIN)

What does this node do?

The Join List node joins two lists of objects on matching properties, similar to a SQL JOIN. It combines objects from both lists when their specified properties match.

Common uses:

  • Merge CRM data with analytics by matching on email or ID
  • Combine Notion databases on a shared key
  • Enrich product data with inventory information

Quick setup

Add the Join List node

Find it in Tools → Join List

Connect both list inputs

Wire two nodes that produce lists of objects to the list_1 and list_2 inputs.

Configure join conditions

Specify which properties to match on (e.g., email in list 1 matches user_email in list 2).

Choose the join type

Select inner, left, right, or full depending on which unmatched items you want to keep.

Use the output

Connect the joined_list output to the next node in your workflow.

Configuration

list_1 json required

The first list of objects to join.

list_2 json required

The second list of objects to join.

join_conditions json

A JSON array of condition objects specifying which properties to match. Each condition has a list1_property and a list2_property.

Example:

[
  { "list1_property": "keyword", "list2_property": "keyword" }
]

Multiple conditions create an AND match — all conditions must be satisfied for two objects to join.

join_type select default: inner

The type of join to perform:

  • inner — only items with a match in both lists
  • left — all items from list_1, with matched data from list_2 (or null if no match)
  • right — all items from list_2, with matched data from list_1 (or null if no match)
  • full — all items from both lists, with null values where no match exists

Output

A JSON array of merged objects. Each result object contains all properties from both matched objects:

{
  "joined_list": [
    { "keyword": "seo tools", "volume": 12000, "rank": 3 },
    { "keyword": "keyword research", "volume": 8500, "rank": 7 }
  ]
}

Access the result: {{JoinList_0.joined_list}}

Examples

Inner join: keywords with rankings

Goal: Match a keyword list with ranking data to see only keywords that appear in both sources.

graph LR
    A[Semrush: Keywords + Volume] --> C[Join List]
    B[Search Console: Keywords + Rank] --> C
    C --> D[LLM: Analyze top keywords]

Configuration:

  • join_conditions: [{"list1_property": "keyword", "list2_property": "keyword"}]
  • join_type: inner

Result: Only keywords present in both Semrush and Search Console, with volume and rank data combined.

Left join: contacts with orders

Goal: List all contacts and attach their order data if any exists.

graph LR
    A[HubSpot: Contacts] --> C[Join List]
    B[Sheets: Orders] --> C
    C --> D[Filter List: No orders]
    C --> E[LLM: Order summary]

Configuration:

  • join_conditions: [{"list1_property": "email", "list2_property": "customer_email"}]
  • join_type: left

Result: All contacts from HubSpot appear in the output. Those with matching orders get the order data attached; those without get null values for order fields.

Full join: complete data view

Goal: Get a complete picture of all products across two systems, whether they exist in one or both.

graph LR
    A[Notion: Product Catalog] --> C[Join List]
    B[Sheets: Inventory] --> C
    C --> D[Loop]
    D --> E[LLM: Generate report]

Configuration:

  • join_conditions: [{"list1_property": "sku", "list2_property": "product_sku"}]
  • join_type: full

Result: Every product from both sources. Products in both get merged data; products in only one source get null values for the missing side.

Best practices

  • Choose the right join type. Use inner when you only need matched records. Use left when the first list is your primary dataset and you want to enrich it. Use full when you need a complete view of both datasets.
  • Ensure property names are correct. The join condition property names must match the exact keys in your objects. Check the raw output of upstream nodes to verify the key names.
  • Handle null values downstream. With left, right, or full joins, unmatched items will have null values for the missing side. Use a Conditional or Code Block to handle these cases.

Common issues

Joined list is empty

No objects matched on the specified properties. Verify that the property names in join_conditions exactly match the keys in your objects (case-sensitive). Inspect the raw data from upstream nodes to check the actual key names.

Missing data in joined objects

If using left, right, or full join, unmatched items will have null values for properties from the other list. This is expected behavior. Add a Filter List or Conditional node to handle null values if needed.

Unexpected duplicates in output

If multiple objects in one list match the same object in the other list, you will get multiple joined results (one per match). This is standard join behavior. Use Remove Duplicates or Filter List after the join if you need unique results.

Merge Lists

Concatenate lists without matching
Filter List

Filter items based on conditions
Notion Database Reader

Read data from Notion databases