Lookup

The Lookup node enriches input rows by joining data from another table. For each input row, it finds the matching row in the target table and attaches it as a nested field. This is similar to a SQL LEFT JOIN.

Configuration

Property	Type	Default	Description
tableId	number	--	Required. The ID of the WP-Nexus table to look up.
localField	string	--	Required. The field in the input row that contains the foreign key.
foreignField	string	id	The field in the target table to match against.
outputField	string	_lookup	The field name where the matched row will be stored.

Input

Accepts a single object or an array of rows. Each row must have the localField with a value to look up.

Output

Returns the same rows with an additional field (outputField) containing the matched row from the target table, or null if no match was found.

Example

Input:

[
  { "id": 1, "product_id": 42, "quantity": 2 },
  { "id": 2, "product_id": 17, "quantity": 1 }
]

Config: tableId: 3, localField: "product_id", foreignField: "id", outputField: "product"

Output:

[
  {
    "id": 1, "product_id": 42, "quantity": 2,
    "product": { "id": 42, "name": "Widget A", "price": 29.99 }
  },
  {
    "id": 2, "product_id": 17, "quantity": 1,
    "product": { "id": 17, "name": "Widget B", "price": 49.99 }
  }
]

How It Works

1. Collects all unique localField values from the input rows.
2. Makes a single batch query: SELECT * FROM target_table WHERE foreignField IN (value1, value2, ...).
3. Indexes the results by foreignField.
4. Attaches the matching row to each input row under outputField.

The batch approach is efficient -- it makes only one database query regardless of how many input rows there are.

Example Use Cases

Enrich order items with product details

tableId: 3         (products table)
localField: "product_id"
foreignField: "id"
outputField: "product"

Access in templates: { {row.product.name}}, { {row.product.price}}

Resolve user names on activity logs

tableId: 8         (users table)
localField: "user_id"
foreignField: "id"
outputField: "user"

Attach category info to products

tableId: 2         (categories table)
localField: "category_id"
foreignField: "id"
outputField: "category"

Display: { {row.category.name}}

Build a cart page with product details

Get Store Items (storeName: "cart")
  --> Lookup (tableId: products, localField: "item_id", foreignField: "id", outputField: "product")
    --> Result

TIP

Lookup is the recommended way to resolve foreign key relationships in display pipelines. For write operations that need to iterate and process each related item, use Related Items or For Each instead.

WARNING

The Lookup node only works with WP-Nexus custom tables. For looking up WordPress posts or terms by ID, use a separate query node.