GUBUS JOIN Transform

Overview

JOIN enriches objects in localObjs by merging data from external sources (side objects (literally previous schemas result) & rules. Think of it as SQL JOIN operations. But GUBUS JOIN for Google Spreadsheets.

Key characteristics:

• 3 join types: FULL_JOIN, SOME_FIELDS_JOIN, BLIND_ONE_OBJ_JOIN
• Joins based on union field matching (like SQL ON clause)
• IS ABLE to rename fields during join with colon syntax
• Optional error handling with break_on_false_join

---

BRAKE_ON_FALSE Behavior

The brake_on_false_join (or break_on_false_join) field controls how the JOIN transform handles cases where a join cannot be made (i.e., a base object does not find a matching join object). This field is configurable and supports three options:

• ignore: Ignores and does not expose falsy joins. Use this when the join is optional and missing data is acceptable.
• inform_error: Continues execution, but accumulates mistakes (failed joins) to expose them after execution. Use this when false joins are allowable, but should be reviewed and repaired in the future.
• brake: On a false join, execution is immediately stopped, the main result is falsified, and no posting or further processing happens. Use this when the join is mandatory and missing data is a critical error.

This allows fine-grained control over error handling in JOIN operations, supporting both strict and flexible data enrichment scenarios.

---

How It Works

[Load join source: side_obj/rule/local]
	→ [Index on union_field_in_join]
	→ [For each local object]
			→ [Lookup by union_field_in_base_obj MATCH to union_field_in_join]
			→ [Merge fields based on join_type]
			→ [Apply field renaming if [:] is present]

Indexing on join field ensures O(1) lookup for large datasets. Failed joins can be ignored or break execution depending on config.

---

Join Types

FULL_JOIN

Copies all fields from joined object to base object.

{
	"join_type": "FULL_JOIN",
	"join_source": "side_obj",
	"join_source_ref": "customerData",
	"union_field_in_base_obj": "customer_id",
	"union_field_in_join": "id"
}

Base: {order_id: "A1", customer_id: "C123", total: 100}
Join: {id: "C123", name: "John Doe", email: "john@example.com", city: "NYC"}
Result: Base object + all join fields (name, email, city)

---

SOME_FIELDS_JOIN

Copies only specified fields from joined object.

{
	"join_type": "SOME_FIELDS_JOIN",
	"union_field_in_base_obj": "customer_id",
	"union_field_in_join": "id",
	"join_fields_if_part_join": "name,email"
}

Result: Base object + only name and email (not city)

---

BLIND_ONE_OBJ_JOIN

Joins first object from join source to all base objects, ignoring union field matching.

Useful for adding configuration/global settings to all objects.

{
	"join_type": "BLIND_ONE_OBJ_JOIN",
	"join_source": "rule",
	"join_source_ref": "globalConfig"
}

Base: [{order_id: "A1", total: 100}, {order_id: "A2", total: 200}]
Join: {tax_rate: 0.08, currency: "USD"}
Result: Both orders get tax_rate and currency fields

---

Field Renaming

Use colon syntax to rename fields during join: source_field:target_field

{
	"join_type": "SOME_FIELDS_JOIN",
	"join_fields_if_part_join": "name:customer_name,email:customer_email"
}

Join: {id: "C123", name: "John Doe", email: "john@example.com"}
Result: Fields added as customer_name and customer_email (not name/email)

---

Rule Properties

PROPERTY	DESCRIPTION
reference	Required. Example: “enrichWithCustomers”
join_type	Required. “FULL_JOIN”, “SOME_FIELDS_JOIN”, or “BLIND_ONE_OBJ_JOIN”
join_source	Required. “side_obj”, “rule”, or “local”
join_source_ref	Required. Reference name of join source
union_field_in_base_obj	Required (except BLIND). Join key in base objects
union_field_in_join	Required (except BLIND). Join key in join source
join_fields_if_part_join	Required for SOME_FIELDS_JOIN. Comma-separated fields. Supports “field:newName”
break_on_false_join	Boolean. Falsify SchemaContext on failed join
false_join_op_message	Custom error message on failed join

---

Common Use Cases

Enrich Orders with Customer Data

{
	"join_type": "SOME_FIELDS_JOIN",
	"join_source": "side_obj",
	"join_source_ref": "loadCustomers",
	"union_field_in_base_obj": "customer_id",
	"union_field_in_join": "id",
	"join_fields_if_part_join": "name:customer_name,email:customer_email"
}

Base: [{order_id: "A1", customer_id: "C123", total: 100}]
Join: [{id: "C123", name: "John Doe", email: "john@example.com"}]
Result: [{order_id: "A1", customer_id: "C123", total: 100, customer_name: "John Doe", customer_email: "john@example.com"}]

---

Add Pricing from Database Rule

{
	"join_type": "SOME_FIELDS_JOIN",
	"join_source": "rule",
	"join_source_ref": "productPricing",
	"union_field_in_base_obj": "product_id",
	"union_field_in_join": "sku",
	"join_fields_if_part_join": "price,discount"
}

Merges pricing data from database rule into product list.

---

Mandatory Join with Error Handling

{
	"join_type": "FULL_JOIN",
	"union_field_in_base_obj": "customer_id",
	"union_field_in_join": "id",
	"break_on_false_join": true,
	"false_join_op_message": "Customer data missing for order"
}

If any customer_id not found in join source, SchemaContext.mainResult = false and execution stops.

Summary

JOIN enriches objects by merging data from multiple sources:

• 3 join types: FULL (all fields), SOME_FIELDS (selected), BLIND (global)
• Union field matching like SQL ON clause
• Field renaming with colon syntax
• Optional error handling