Add extend() method as semantic alias for left join

A.extend(B) is equivalent to A.join(B, left=True) but expresses clearer
intent: extending an entity set with additional attributes rather than
combining two entity sets.

- Add extend() method to QueryExpression
- Add 'extend' to supported_class_attrs for class-level access
- Update pk-rules-spec.md to document extend as actual API
- Add integration tests for valid and invalid extend cases

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: dimitri-yatsenko

docs/src/design/pk-rules-spec.md

@@ -38,6 +38,7 @@ In the examples below, `*` marks primary key attributes:
 | `A - B` (anti-restriction) | PK(A) — preserved from left operand |
 | `A.proj(...)` (projection) | PK(A) — preserved from left operand |
 | `A.aggr(B, ...)` (aggregation) | PK(A) — preserved from left operand |
+| `A.extend(B)` (extension) | PK(A) — requires A → B |
 | `A * B` (join) | Depends on functional dependencies (see below) |
 
 ### Join Primary Key Rule
@@ -203,6 +204,47 @@ The following attributes from the right operand's primary key are not determined
 the left operand: ['z']. Use an inner join or restructure the query.
 ```
 
+### Conceptual Note: Left Join as Extension
+
+When `A → B`, the left join `A.join(B, left=True)` is conceptually distinct from the general join operator `A * B`. It is better understood as an **extension** operation rather than a join:
+
+| Aspect | General Join (A * B) | Left Join when A → B |
+|--------|---------------------|----------------------|
+| Conceptual model | Cartesian product restricted to matching rows | Extend A with attributes from B |
+| Row count | May increase, decrease, or stay same | Always equals len(A) |
+| Primary key | Depends on functional dependencies | Always PK(A) |
+| Relation to projection | Different operation | Variation of projection |
+
+**The extension perspective:**
+
+The operation `A.join(B, left=True)` when `A → B` is closer to **projection** than to **join**:
+- It adds new attributes to A (like `A.proj(..., new_attr=...)`)
+- It preserves all rows of A
+- It preserves A's primary key
+- It lacks the Cartesian product aspect that defines joins
+
+DataJoint provides an explicit `extend()` method for this pattern:
+
+```python
+# These are equivalent when A → B:
+A.join(B, left=True)
+A.extend(B)           # clearer intent: extend A with B's attributes
+```
+
+The `extend()` method:
+- Requires `A → B` (raises `DataJointError` otherwise)
+- Does not expose `allow_nullable_pk` (that's an internal mechanism)
+- Expresses the semantic intent: "add B's attributes to A's entities"
+
+**Relationship to aggregation:**
+
+A similar argument applies to `A.aggr(B, ...)`:
+- It preserves A's primary key
+- It adds computed attributes derived from B
+- It's conceptually a variation of projection with grouping
+
+Both `A.join(B, left=True)` (when A → B) and `A.aggr(B, ...)` can be viewed as **projection-like operations** that extend A's attributes while preserving its entity identity.
+
 ### Bypassing the Left Join Constraint
 
 For special cases where the user takes responsibility for handling the potentially nullable primary key, the constraint can be bypassed using `allow_nullable_pk=True`:

src/datajoint/expression.py

@@ -360,6 +360,45 @@ def join(self, other, semantic_check=True, left=False, allow_nullable_pk=False):
         assert len(result.support) == len(result._left) + 1
         return result
 
+    def extend(self, other, semantic_check=True):
+        """
+        Extend self with attributes from other.
+
+        The extend operation adds attributes from `other` to `self` while preserving
+        self's entity identity. It is semantically equivalent to `self.join(other, left=True)`
+        but expresses a clearer intent: extending an entity set with additional attributes
+        rather than combining two entity sets.
+
+        Requirements:
+            self → other: Every attribute in other's primary key must exist in self.
+            This ensures:
+            - All rows of self are preserved (no filtering)
+            - Self's primary key remains the result's primary key (no NULL PKs)
+            - The operation is a true extension, not a Cartesian product
+
+        Conceptual model:
+            Unlike a general join (Cartesian product restricted by matching attributes),
+            extend is closer to projection—it adds new attributes to existing entities
+            without changing which entities are in the result.
+
+        Example:
+            # Session determines Trial (session_id is in Trial's PK)
+            # But Trial does NOT determine Session (trial_num not in Session)
+
+            # Valid: extend trials with session info
+            Trial.extend(Session)  # Adds 'date' from Session to each Trial
+
+            # Invalid: Session cannot extend to Trial
+            Session.extend(Trial)  # Error: trial_num not in Session
+
+        :param other: QueryExpression whose attributes will extend self
+        :param semantic_check: If True (default), require homologous namesakes.
+            If False, match on all namesakes without lineage checking.
+        :return: Extended QueryExpression with self's PK and combined attributes
+        :raises DataJointError: If self does not determine other
+        """
+        return self.join(other, semantic_check=semantic_check, left=True)
+
     def __add__(self, other):
         """union e.g. ``q1 + q2``."""
         return Union.create(self, other)

src/datajoint/user_tables.py

@@ -25,6 +25,7 @@
     "proj",
     "aggr",
     "join",
+    "extend",
     "fetch",
     "fetch1",
     "head",

tests/integration/test_aggr_regressions.py

@@ -147,3 +147,36 @@ def test_left_join_valid(schema_uuid):
     assert len(q) == len(qf)
     # All Items should have matching Topics since they were populated from Topics
     assert len(q) == len(Item())
+
+
+def test_extend_valid(schema_uuid):
+    """extend() is an alias for join(left=True) when A → B."""
+    # Clean up from previous tests
+    Item().delete_quick()
+    Topic().delete_quick()
+
+    Topic().add("alice")
+    Item.populate()
+    # Item → Topic (topic_id is in Item), so extend is valid
+    q_extend = Item.extend(Topic)
+    q_left_join = Item.join(Topic, left=True)
+    # Should produce identical results
+    assert len(q_extend) == len(q_left_join)
+    assert set(q_extend.heading.names) == set(q_left_join.heading.names)
+    assert q_extend.primary_key == q_left_join.primary_key
+
+
+def test_extend_invalid_raises_error(schema_uuid):
+    """extend() requires A → B. Topic ↛ Item, so this should raise an error."""
+    from datajoint.errors import DataJointError
+
+    # Clean up from previous tests
+    Item().delete_quick()
+    Topic().delete_quick()
+
+    Topic().add("bob")
+    Item.populate()
+    # Topic ↛ Item (item_id not in Topic), so extend should fail
+    with pytest.raises(DataJointError) as exc_info:
+        Topic.extend(Item)
+    assert "left operand to determine" in str(exc_info.value).lower()