Add left join constraint requiring A → B for valid primary key

Left joins (A.join(B, left=True)) can produce NULL values for attributes
from B when rows in A have no matching rows in B. This would result in
NULL primary key values if B's primary key attributes are included in
the result's primary key.

To prevent this, left joins now require A → B (the left operand must
functionally determine the right operand). This ensures PK = PK(A),
which consists entirely of non-NULL values from the left operand.

Changes:
- heading.join() now accepts 'left' parameter and validates A → B
- expression.py passes 'left' parameter to heading.join()
- Added tests for left join constraint validation
- Updated spec with left join rules and rationale

Co-authored-by: dimitri-yatsenko<dimitri@datajoint.com>

Author: claude

docs/src/design/semantic-matching-spec.md

@@ -302,6 +302,45 @@ With these rules, join is **not commutative** in terms of:
 
 The **result set** (the actual rows returned) remains the same regardless of order, but the **schema** (primary key and attribute order) may differ.
 
+### Left Join Constraint
+
+For left joins (`A.join(B, left=True)`), the functional dependency **A → B is required**.
+
+**Why this constraint exists:**
+
+In a left join, all rows from A are retained even if there's no matching row in B. For unmatched rows, B's attributes are NULL. This creates a problem for primary key validity:
+
+| Scenario | PK by inner join rule | Left join problem |
+|----------|----------------------|-------------------|
+| A → B | PK(A) | ✅ Safe — A's attrs always present |
+| B → A | PK(B) | ❌ B's PK attrs could be NULL |
+| Neither | PK(A) ∪ PK(B) | ❌ B's PK attrs could be NULL |
+
+**Example of invalid left join:**
+```
+A: x*, y*           PK(A) = {x, y}
+B: x*, z*, y        PK(B) = {x, z}, y is secondary
+
+Inner join: PK = {x, z} (B → A rule)
+Left join attempt: FAILS because z could be NULL for unmatched A rows
+```
+
+**Valid left join example:**
+```
+Session: session_id*, date
+Trial: session_id*, trial_num*, stimulus    (references Session)
+
+Session.join(Trial, left=True)  # OK: Session → Trial
+# PK = {session_id}, all sessions retained even without trials
+```
+
+**Error message:**
+```
+DataJointError: Left join requires the left operand to determine the right operand (A → B).
+The following attributes from the right operand's primary key are not determined by
+the left operand: ['z']. Use an inner join or restructure the query.
+```
+
 ## Universal Set `dj.U`
 
 `dj.U()` or `dj.U('attr1', 'attr2', ...)` represents the universal set of all possible values and lineages.

src/datajoint/expression.py

@@ -336,10 +336,10 @@ def join(self, other, semantic_check=True, left=False):
         result._connection = self.connection
         result._support = self.support + other.support
         result._left = self._left + [left] + other._left
-        result._heading = self.heading.join(other.heading)
+        result._heading = self.heading.join(other.heading, left=left)
         result._restriction = AndList(self.restriction)
         result._restriction.append(other.restriction)
-        result._original_heading = self.original_heading.join(other.original_heading)
+        result._original_heading = self.original_heading.join(other.original_heading, left=left)
         assert len(result.support) == len(result._left) + 1
         return result
 

src/datajoint/heading.py

@@ -468,7 +468,7 @@ def select(self, select_list, rename_map=None, compute_map=None):
         )
         return Heading(chain(copy_attrs, compute_attrs))
 
-    def join(self, other):
+    def join(self, other, left=False):
         """
         Join two headings into a new one.
 
@@ -480,8 +480,20 @@ def join(self, other):
         A → B holds iff every attribute in PK(B) is either in PK(A) or secondary in A.
         B → A holds iff every attribute in PK(A) is either in PK(B) or secondary in B.
 
+        For left joins (left=True), A → B is required. Otherwise, the result would not
+        have a valid primary key because:
+        - Unmatched rows from A have NULL values for B's attributes
+        - If B → A or Neither, the PK would include B's attributes, which could be NULL
+        - Only when A → B does PK(A) uniquely identify all result rows
+
         It assumes that self and other are headings that share no common dependent attributes.
+
+        :param other: The other heading to join with
+        :param left: If True, this is a left join (requires A → B)
+        :raises DataJointError: If left=True and A does not determine B
         """
+        from .errors import DataJointError
+
         # Check functional dependencies
         self_determines_other = all(
             name in self.primary_key or name in self.secondary_attributes for name in other.primary_key
@@ -490,10 +502,22 @@ def join(self, other):
             name in other.primary_key or name in other.secondary_attributes for name in self.primary_key
         )
 
+        # For left joins, require A → B
+        if left and not self_determines_other:
+            missing = [
+                name for name in other.primary_key if name not in self.primary_key and name not in self.secondary_attributes
+            ]
+            raise DataJointError(
+                f"Left join requires the left operand to determine the right operand (A → B). "
+                f"The following attributes from the right operand's primary key are not "
+                f"determined by the left operand: {missing}. "
+                f"Use an inner join or restructure the query."
+            )
+
         seen = set()
         result_attrs = []
 
-        if self_determines_other:
+        if left or self_determines_other:
             # A → B: use PK(A), A's attributes first
             # 1. All of A's PK attrs (as PK)
             for name in self.primary_key:

tests/test_semantic_matching.py

@@ -670,3 +670,87 @@ def test_pk_attributes_come_first(self, schema_pk_rules):
 
         if secondary_indices:  # If there are secondary attributes
             assert max(pk_indices) < min(secondary_indices)
+
+
+class TestLeftJoinConstraint:
+    """
+    Test that left joins require A → B (left operand determines right operand).
+
+    For left joins, B's attributes could be NULL for unmatched rows, so the PK
+    must be PK(A) only. This is only valid when A → B.
+    """
+
+    def test_left_join_valid_when_a_determines_b(self, schema_pk_rules):
+        """
+        Left join should work when A → B.
+
+        A: x*, y*, z        PK(A) = {x, y}, z is secondary
+        B: y*, z*, x        PK(B) = {y, z}, x is secondary
+
+        A → B? z secondary in A → Yes
+        Left join is valid, PK = {x, y}
+        """
+        TableXYwithZ = schema_pk_rules["TableXYwithZ"]
+        TableYZwithX = schema_pk_rules["TableYZwithX"]
+
+        # This should work - A → B holds
+        result = TableXYwithZ().join(TableYZwithX(), left=True)
+
+        # PK should be PK(A) = {x, y}
+        assert set(result.primary_key) == {"x", "y"}
+
+    def test_left_join_fails_when_b_determines_a_only(self, schema_pk_rules):
+        """
+        Left join should fail when only B → A (not A → B).
+
+        A: x*, y*           PK(A) = {x, y}
+        B: x*, z*, y        PK(B) = {x, z}, y is secondary
+
+        A → B? z not in PK(A) and z not secondary in A → No
+        B → A? y secondary in B → Yes
+
+        Left join is invalid because z would need to be in PK but could be NULL.
+        """
+        TableXY = schema_pk_rules["TableXY"]
+        TableXZwithY = schema_pk_rules["TableXZwithY"]
+
+        # This should fail - A → B does not hold
+        with pytest.raises(DataJointError) as exc_info:
+            TableXY().join(TableXZwithY(), left=True)
+
+        assert "Left join requires" in str(exc_info.value)
+        assert "A → B" in str(exc_info.value) or "determine" in str(exc_info.value)
+
+    def test_left_join_fails_when_neither_direction(self, schema_pk_rules):
+        """
+        Left join should fail when neither A → B nor B → A.
+
+        A: x*, y*           PK(A) = {x, y}
+        B: z*, x            PK(B) = {z}, x is secondary
+
+        A → B? z not in A → No
+        B → A? y not in B → No
+
+        Left join is invalid.
+        """
+        TableXY = schema_pk_rules["TableXY"]
+        TableZ = schema_pk_rules["TableZ"]
+
+        # This should fail - A → B does not hold
+        with pytest.raises(DataJointError) as exc_info:
+            TableXY().join(TableZ(), left=True)
+
+        assert "Left join requires" in str(exc_info.value)
+
+    def test_inner_join_still_works_when_b_determines_a(self, schema_pk_rules):
+        """
+        Inner join should still work normally when B → A (even though left join fails).
+        """
+        TableXY = schema_pk_rules["TableXY"]
+        TableXZwithY = schema_pk_rules["TableXZwithY"]
+
+        # Inner join should work - B → A applies
+        result = TableXY * TableXZwithY
+
+        # PK should be {x, z} (B's PK)
+        assert set(result.primary_key) == {"x", "z"}