Implement semantic matching for joins

Phase 2-4: Core semantic matching implementation

- Load lineage into Heading when initializing from table_info
- Add get_homologous_namesakes() to find attributes with same name and lineage
- Update assert_join_compatibility() for semantic matching:
  - Homologous namesakes (same lineage) -> allowed
  - Non-homologous namesakes (different lineage) -> error with guidance
- Modify join() to use homologous namesakes instead of all namesakes
- Remove @ operator (raises error directing to .join(semantic_check=False))

Joins now require attributes to have matching lineage, not just matching names.
This prevents accidental joins on coincidentally-named attributes.

Author: claude

datajoint/condition.py

@@ -101,15 +101,45 @@ def __init__(self, restriction):
         self.restriction = restriction
 
 
+def get_homologous_namesakes(expr1, expr2):
+    """
+    Find attributes that are namesakes (same name) and homologous (same lineage).
+
+    :param expr1: A QueryExpression object
+    :param expr2: A QueryExpression object
+    :return: set of attribute names that are homologous namesakes
+    """
+    from .expression import U
+
+    if isinstance(expr1, U) or isinstance(expr2, U):
+        # For U, fall back to simple name matching
+        return set(expr1.heading.names) & set(expr2.heading.names)
+
+    namesakes = set(expr1.heading.names) & set(expr2.heading.names)
+    homologous = set()
+
+    for attr in namesakes:
+        lineage1 = expr1.heading.get_lineage(attr)
+        lineage2 = expr2.heading.get_lineage(attr)
+
+        # Homologous if both have lineage and lineages match
+        if lineage1 is not None and lineage2 is not None and lineage1 == lineage2:
+            homologous.add(attr)
+
+    return homologous
+
+
 def assert_join_compatibility(expr1, expr2):
     """
-    Determine if expressions expr1 and expr2 are join-compatible.  To be join-compatible,
-    the matching attributes in the two expressions must be in the primary key of one or the
-    other expression.
-    Raises an exception if not compatible.
+    Determine if expressions expr1 and expr2 are join-compatible using semantic matching.
+
+    For each namesake attribute (same name in both expressions):
+    - If they have the same lineage (homologous), they can be joined
+    - If they have different lineage (non-homologous), raise an error
 
     :param expr1: A QueryExpression object
     :param expr2: A QueryExpression object
+    :raises DataJointError: if non-homologous namesakes are found
     """
     from .expression import QueryExpression, U
 
@@ -118,21 +148,42 @@ def assert_join_compatibility(expr1, expr2):
             raise DataJointError(
                 "Object %r is not a QueryExpression and cannot be joined." % rel
             )
-    if not isinstance(expr1, U) and not isinstance(
-        expr2, U
-    ):  # dj.U is always compatible
-        try:
-            raise DataJointError(
-                "Cannot join query expressions on dependent attribute `%s`"
-                % next(
-                    r
-                    for r in set(expr1.heading.secondary_attributes).intersection(
-                        expr2.heading.secondary_attributes
-                    )
+
+    if isinstance(expr1, U) or isinstance(expr2, U):
+        return  # dj.U is always compatible
+
+    # Find namesake attributes (same name in both expressions)
+    namesakes = set(expr1.heading.names) & set(expr2.heading.names)
+
+    for attr in namesakes:
+        lineage1 = expr1.heading.get_lineage(attr)
+        lineage2 = expr2.heading.get_lineage(attr)
+
+        # Check if they are homologous (same lineage)
+        # None lineages are never homologous (not even with each other)
+        if lineage1 is None or lineage2 is None or lineage1 != lineage2:
+            # Non-homologous namesakes - error
+            if lineage1 is None and lineage2 is None:
+                msg = (
+                    f"Cannot join: attribute '{attr}' has no lineage in both operands "
+                    f"(native secondary attributes). Use .proj() to rename one."
                 )
-            )
-        except StopIteration:
-            pass  # all ok
+            elif lineage1 is None:
+                msg = (
+                    f"Cannot join: attribute '{attr}' has lineage '{lineage2}' in one operand "
+                    f"but no lineage in the other. Use .proj() to rename one."
+                )
+            elif lineage2 is None:
+                msg = (
+                    f"Cannot join: attribute '{attr}' has lineage '{lineage1}' in one operand "
+                    f"but no lineage in the other. Use .proj() to rename one."
+                )
+            else:
+                msg = (
+                    f"Cannot join: attribute '{attr}' has different lineages "
+                    f"('{lineage1}' vs '{lineage2}'). Use .proj() to rename one."
+                )
+            raise DataJointError(msg)
 
 
 def make_condition(query_expression, condition, columns):

datajoint/expression.py

@@ -11,6 +11,7 @@
     Top,
     assert_join_compatibility,
     extract_column_names,
+    get_homologous_namesakes,
     make_condition,
     translate_attribute,
 )
@@ -292,19 +293,22 @@ def __mul__(self, other):
 
     def __matmul__(self, other):
         """
-        Permissive join of query expressions `self` and `other` ignoring compatibility check
-            e.g. ``q1 @ q2``.
+        The @ operator has been removed. Use .join(semantic_check=False) instead.
         """
-        if inspect.isclass(other) and issubclass(other, QueryExpression):
-            other = other()  # instantiate
-        return self.join(other, semantic_check=False)
+        raise DataJointError(
+            "The @ operator has been removed in DataJoint 2.0. "
+            "Use .join(other, semantic_check=False) instead."
+        )
 
     def join(self, other, semantic_check=True, left=False):
         """
         create the joined QueryExpression.
         a * b  is short for A.join(B)
-        a @ b  is short for A.join(B, semantic_check=False)
+        a @ b  is short for A.join(B, semantic_check=False) -- DEPRECATED
         Additionally, left=True will retain the rows of self, effectively performing a left join.
+
+        With semantic matching (semantic_check=True), joins are performed only on
+        homologous namesakes (attributes with same name AND same lineage).
         """
         # trigger subqueries if joining on renamed attributes
         if isinstance(other, U):
@@ -315,7 +319,11 @@ def join(self, other, semantic_check=True, left=False):
             raise DataJointError("The argument of join must be a QueryExpression")
         if semantic_check:
             assert_join_compatibility(self, other)
-        join_attributes = set(n for n in self.heading.names if n in other.heading.names)
+            # Use semantic matching: only join on homologous namesakes
+            join_attributes = get_homologous_namesakes(self, other)
+        else:
+            # Permissive mode: join on all namesakes regardless of lineage
+            join_attributes = set(n for n in self.heading.names if n in other.heading.names)
         # needs subquery if self's FROM clause has common attributes with other's FROM clause
         need_subquery1 = need_subquery2 = bool(
             (set(self.original_heading.names) & set(other.original_heading.names))

datajoint/heading.py

@@ -433,6 +433,17 @@ def _init_from_database(self):
                 # restore adapted type name
                 attr["type"] = adapter_name
 
+        # Load lineage information for semantic matching
+        try:
+            from .lineage import get_lineage_for_heading
+
+            lineage_map = get_lineage_for_heading(conn, database, table_name, None)
+            for attr in attributes:
+                attr["lineage"] = lineage_map.get(attr["name"])
+        except Exception as e:
+            # If lineage loading fails, continue without it (backward compatibility)
+            logger.debug(f"Could not load lineage for {database}.{table_name}: {e}")
+
         self._attributes = dict(((q["name"], Attribute(**q)) for q in attributes))
 
         # Read and tabulate secondary indexes