relationalai 0.12.0__py3-none-any.whl → 0.12.1__py3-none-any.whl

relationalai/semantics/reasoners/graph/core.py

@@ -1056,6 +1056,181 @@ class Graph():
 
     # End Visualization --------------------------------------------------------
 
+    # The following three helper methods validate
+    # `from_`, `to`, and `between`
+    # parameters to public methods that accept them.
+
+    def _validate_domain_constraint_parameters(
+            self,
+            method_name: str,
+            full: Optional[bool],
+            from_: Optional[Relationship],
+            to: Optional[Relationship],
+            between: Optional[Relationship],
+        ):
+        """
+        Validate the domain constraint parameters for methods that accept
+        `full`, `from_`, `to`, and `between` parameters.
+
+        This helper method performs common validation logic that applies
+        across multiple graph methods (e.g., common_neighbor, adamic_adar).
+
+        Parameters
+        ----------
+        method_name : str
+            The name of the method being validated (for error messages).
+        full : bool, optional
+            The full parameter value.
+        from_ : Relationship, optional
+            The from_ parameter value.
+        to : Relationship, optional
+            The to parameter value.
+        between : Relationship, optional
+            The between parameter value.
+
+        Raises
+        ------
+        ValueError
+            If parameter combinations are invalid.
+        """
+        # Confirm that `full` was not provided with any other parameter.
+        if (
+            full is not None
+            and (
+                from_ is not None or
+                to is not None or
+                between is not None
+            )
+        ):
+            raise ValueError(
+                "The 'full' parameter is mutually exclusive with 'from_', 'to', and 'between'. "
+                f"Use 'full=True' to compute {method_name} for all node pairs, "
+                "or use 'from_'/'to'/'between' to constrain computation to "
+                "specific nodes or pairs."
+            )
+
+        # Confirm that `between` was not provided with any other parameter.
+        if (between is not None
+            and (
+                from_ is not None or
+                to is not None
+                # `full` is implied by the preceding check.
+            )
+        ):
+            raise ValueError(
+                "The 'between' parameter is mutually exclusive with 'from_' and 'to'. "
+                "Use 'between' to constrain computation to specific node pairs, "
+                "or use 'from_'/'to' to constrain by position."
+            )
+
+        # Confirm that 'to' is only used with 'from_'.
+        if to is not None and from_ is None:
+            raise ValueError(
+                "The 'to' parameter can only be used together with the 'from_' parameter. "
+                f"The 'from_' parameter constrains the first position in {method_name} tuples, "
+                f"while 'to' constrains the second position. Since {method_name} is symmetric "
+                "in its first two positions, 'to' without 'from_' would be functionally redundant. "
+                "Please either provide both 'from_' and 'to' parameters, or only 'from_'."
+            )
+
+        # If no parameters are provided, raise an exception
+        # to avoid unintentional, potentially expensive full computation.
+        if (
+            full is None and
+            from_ is None and
+            between is None
+        ):
+            raise ValueError(
+                f"Computing {method_name} for all pairs of nodes can be expensive. "
+                f"To compute the full {method_name} relationship, "
+                f"please call `{method_name}(full=True)`. To constrain computation to specific nodes, "
+                f"please use `{method_name}(from_=node_subset)`, "
+                f"`{method_name}(from_=node_subset_a, to=node_subset_b)`, "
+                f"or `{method_name}(between=node_pairs)`."
+            )
+
+        # Validate that full is True (not just not None).
+        # This check is only reached if full is not None
+        # and no other parameters are provided.
+        if full is not None and full is not True:
+            raise ValueError(
+                f"Invalid value (`{full}`) for 'full' parameter. Use `full=True` "
+                f"to compute the full {method_name} relationship, or use 'from_', "
+                "'from_' and 'to', or 'between' to constrain computation."
+            )
+
+    def _validate_node_subset_parameter(
+            self,
+            parameter_name: str,
+            node_subset_relation: Relationship,
+        ):
+        """
+        Validate that a parameter identifying a subset of nodes of interest is
+        is a unary relationship, of nodes, attached to the same model
+        that the graph is attached to.
+        """
+        # Validate that the parameter is a relationship.
+        assert isinstance(node_subset_relation, Relationship), (
+            f"The '{parameter_name}' parameter must be a `Relationship`, "
+            f"but is a `{type(node_subset_relation).__name__}`."
+        )
+
+        # Validate that the relationship is attached to the same model as the graph.
+        assert node_subset_relation._model is self._model, (
+            f"The given '{parameter_name}' relationship must "
+            "be attached to the same model as the graph."
+        )
+
+        # Validate that it's a unary relationship (has exactly one field).
+        assert len(node_subset_relation._fields) == 1, (
+            f"The '{parameter_name}' parameter must be a unary relationship, "
+            f"but it has {len(node_subset_relation._fields)} fields."
+        )
+
+        # Validate that the concept type matches the graph's Node concept.
+        assert node_subset_relation._fields[0].type_str == self.Node._name, (
+            f"The '{parameter_name}' relationship must be over "
+            f"the graph's Node concept ('{self.Node._name}'), "
+            f"but is over '{node_subset_relation._fields[0].type_str}'."
+        )
+
+    # No parameter name at this time, as pertains only to `between` for now.
+    def _validate_pair_subset_parameter(self, pairs_relation):
+        """
+        Validate that a parameter identifying pairs of nodes of interest is
+        a binary relationship, of pairs of nodes, attached to the same model
+        that the graph is attached to.
+        """
+        # Validate that the parameter is a relationship.
+        assert isinstance(pairs_relation, Relationship), (
+            "The 'between' parameter must be a `Relationship`, "
+            f"but is a `{type(pairs_relation).__name__}`."
+        )
+
+        # Validate that the relationship is attached to the same model as the graph.
+        assert pairs_relation._model is self._model, (
+            "The given 'between' relationship must be "
+            "attached to the same model as the graph."
+        )
+
+        # Validate that it's a binary relationship (has exactly two fields).
+        assert len(pairs_relation._fields) == 2, (
+            "The 'between' parameter must be a binary relationship, "
+            f"but it has {len(pairs_relation._fields)} fields."
+        )
+
+        # Validate that both fields are typed as the graph's Node concept.
+        assert pairs_relation._fields[0].type_str == self.Node._name, (
+            "The 'between' relationship's first field must be "
+            f"the graph's Node concept ('{self.Node._name}'), "
+            f"but is '{pairs_relation._fields[0].type_str}'."
+        )
+        assert pairs_relation._fields[1].type_str == self.Node._name, (
+            f"The 'between' relationship's second field must be "
+            f"the graph's Node concept ('{self.Node._name}'), "
+            f"but is '{pairs_relation._fields[1].type_str}'."
+        )
+
 
     # The following three `_count_[in,out]neighbor` relationships are
     # primarily for internal consumption. They differ from corresponding
@@ -1065,26 +1240,26 @@ class Graph():
     @cached_property
     def _count_neighbor(self):
         """Lazily define and cache the self._count_neighbor relationship."""
-        return self._create_count_neighbor_relationship(nodes_subset=None)
+        return self._create_count_neighbor_relationship(node_subset=None)
 
-    def _count_neighbor_of(self, nodes_subset: Relationship):
+    def _count_neighbor_of(self, node_subset: Relationship):
         """
         Create a _count_neighbor relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        return self._create_count_neighbor_relationship(nodes_subset=nodes_subset)
+        return self._create_count_neighbor_relationship(node_subset=node_subset)
 
-    def _create_count_neighbor_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_count_neighbor_relationship(self, *, node_subset: Optional[Relationship]):
         _count_neighbor_rel = self._model.Relationship(f"{{src:{self._NodeConceptStr}}} has neighbor count {{count:Integer}}")
 
         # Choose the appropriate neighbor relationship based on whether we have constraints
-        if nodes_subset is None:
+        if node_subset is None:
             # No constraint - use cached neighbor relationship
             neighbor_rel = self._neighbor
         else:
             # Constrained to nodes in the subset - use constrained neighbor relationship
-            neighbor_rel = self._neighbor_of(nodes_subset)
+            neighbor_rel = self._neighbor_of(node_subset)
 
         # Apply the same counting logic for both cases
         src, dst = self.Node.ref(), self.Node.ref()
@@ -1095,26 +1270,26 @@ class Graph():
     @cached_property
     def _count_inneighbor(self):
         """Lazily define and cache the self._count_inneighbor relationship."""
-        return self._create_count_inneighbor_relationship(nodes_subset=None)
+        return self._create_count_inneighbor_relationship(node_subset=None)
 
-    def _count_inneighbor_of(self, nodes_subset: Relationship):
+    def _count_inneighbor_of(self, node_subset: Relationship):
         """
         Create a _count_inneighbor relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        return self._create_count_inneighbor_relationship(nodes_subset=nodes_subset)
+        return self._create_count_inneighbor_relationship(node_subset=node_subset)
 
-    def _create_count_inneighbor_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_count_inneighbor_relationship(self, *, node_subset: Optional[Relationship]):
         _count_inneighbor_rel = self._model.Relationship(f"{{dst:{self._NodeConceptStr}}} has inneighbor count {{count:Integer}}")
 
         # Choose the appropriate inneighbor relationship based on whether we have constraints
-        if nodes_subset is None:
+        if node_subset is None:
             # No constraint - use cached inneighbor relationship
             inneighbor_rel = self._inneighbor
         else:
             # Constrained to nodes in the subset - use constrained inneighbor relationship
-            inneighbor_rel = self._inneighbor_of(nodes_subset)
+            inneighbor_rel = self._inneighbor_of(node_subset)
 
         # Apply the same counting logic for both cases
         dst, src = self.Node.ref(), self.Node.ref()
@@ -1125,26 +1300,26 @@ class Graph():
     @cached_property
     def _count_outneighbor(self):
         """Lazily define and cache the self._count_outneighbor relationship."""
-        return self._create_count_outneighbor_relationship(nodes_subset=None)
+        return self._create_count_outneighbor_relationship(node_subset=None)
 
-    def _count_outneighbor_of(self, nodes_subset: Relationship):
+    def _count_outneighbor_of(self, node_subset: Relationship):
         """
         Create a _count_outneighbor relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        return self._create_count_outneighbor_relationship(nodes_subset=nodes_subset)
+        return self._create_count_outneighbor_relationship(node_subset=node_subset)
 
-    def _create_count_outneighbor_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_count_outneighbor_relationship(self, *, node_subset: Optional[Relationship]):
         _count_outneighbor_rel = self._model.Relationship(f"{{src:{self._NodeConceptStr}}} has outneighbor count {{count:Integer}}")
 
         # Choose the appropriate outneighbor relationship based on whether we have constraints
-        if nodes_subset is None:
+        if node_subset is None:
             # No constraint - use cached outneighbor relationship
             outneighbor_rel = self._outneighbor
         else:
             # Constrained to nodes in the subset - use constrained outneighbor relationship
-            outneighbor_rel = self._outneighbor_of(nodes_subset)
+            outneighbor_rel = self._outneighbor_of(node_subset)
 
         # Apply the same counting logic for both cases
         src, dst = self.Node.ref(), self.Node.ref()
@@ -1437,56 +1612,27 @@ class Graph():
             return self._neighbor
         else:
             # Validate the 'of' parameter
-            self._validate_node_subset_parameter(of)
+            self._validate_node_subset_parameter('of', of)
             return self._neighbor_of(of)
 
-    def _validate_node_subset_parameter(self, of_relation):
-        """
-        Validate that a parameter identifying a subset of nodes of interest is
-        is a unary relationship containing nodes that is attached to
-        the same model that the graph is attached to.
-        """
-        # Validate that the parameter is a relationship.
-        assert isinstance(of_relation, Relationship), (
-            "The 'of' parameter must be a `Relationship`, "
-            f"but is a `{type(of_relation).__name__}`."
-        )
-
-        # Validate that the relationship is attached to the same model as the graph.
-        assert of_relation._model is self._model, (
-            "The given 'of' relationship must be attached to the same model as the graph."
-        )
-
-        # Validate that it's a unary relationship (has exactly one field).
-        assert len(of_relation._fields) == 1, (
-            "The 'of' parameter must be a unary relationship, "
-            f"but it has {len(of_relation._fields)} fields."
-        )
-
-        # Validate that the concept type matches the graph's Node concept.
-        assert of_relation._fields[0].type_str == self.Node._name, (
-            f"The 'of' relationship must be over the graph's Node concept ('{self.Node._name}'), "
-            f"but is over '{of_relation._fields[0].type_str}'."
-        )
-
     @cached_property
     def _neighbor(self):
         """Lazily define and cache the self._neighbor relationship."""
-        _neighbor_rel = self._create_neighbor_relationship(nodes_subset=None)
+        _neighbor_rel = self._create_neighbor_relationship(node_subset=None)
         _neighbor_rel.annotate(annotations.track("graphs", "neighbor"))
         return _neighbor_rel
 
-    def _neighbor_of(self, nodes_subset: Relationship):
+    def _neighbor_of(self, node_subset: Relationship):
         """
         Create a neighbor relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        _neighbor_rel = self._create_neighbor_relationship(nodes_subset=nodes_subset)
+        _neighbor_rel = self._create_neighbor_relationship(node_subset=node_subset)
         _neighbor_rel.annotate(annotations.track("graphs", "neighbor_of"))
         return _neighbor_rel
 
-    def _create_neighbor_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_neighbor_relationship(self, *, node_subset: Optional[Relationship]):
         _neighbor_rel = self._model.Relationship(f"{{src:{self._NodeConceptStr}}} has neighbor {{dst:{self._NodeConceptStr}}}")
         src, dst = self.Node.ref(), self.Node.ref()
 
@@ -1497,14 +1643,14 @@ class Graph():
             # Capture out-neighbors.
             where(
                 self._edge(src, dst),
-                *([nodes_subset(src)] if nodes_subset else [])
+                *([node_subset(src)] if node_subset else [])
             ).define(
                 _neighbor_rel(src, dst)
             )
             # Capture in-neighbors.
             where(
                 self._edge(src, dst),
-                *([nodes_subset(dst)] if nodes_subset else [])
+                *([node_subset(dst)] if node_subset else [])
             ).define(
                 _neighbor_rel(dst, src)
             )
@@ -1513,7 +1659,7 @@ class Graph():
             # so a single rule suffices to capture all neighbors.
             where(
                 self._edge(src, dst),
-                *([nodes_subset(src)] if nodes_subset else [])
+                *([node_subset(src)] if node_subset else [])
             ).define(
                 _neighbor_rel(src, dst)
             )
@@ -1628,27 +1774,27 @@ class Graph():
             return self._inneighbor
         else:
             # Validate the 'of' parameter
-            self._validate_node_subset_parameter(of)
+            self._validate_node_subset_parameter('of', of)
             return self._inneighbor_of(of)
 
     @cached_property
     def _inneighbor(self):
         """Lazily define and cache the self._inneighbor relationship."""
-        _inneighbor_rel = self._create_inneighbor_relationship(nodes_subset=None)
+        _inneighbor_rel = self._create_inneighbor_relationship(node_subset=None)
         _inneighbor_rel.annotate(annotations.track("graphs", "inneighbor"))
         return _inneighbor_rel
 
-    def _inneighbor_of(self, nodes_subset: Relationship):
+    def _inneighbor_of(self, node_subset: Relationship):
         """
         Create an inneighbor relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        _inneighbor_rel = self._create_inneighbor_relationship(nodes_subset=nodes_subset)
+        _inneighbor_rel = self._create_inneighbor_relationship(node_subset=node_subset)
         _inneighbor_rel.annotate(annotations.track("graphs", "inneighbor_of"))
         return _inneighbor_rel
 
-    def _create_inneighbor_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_inneighbor_relationship(self, *, node_subset: Optional[Relationship]):
         _inneighbor_rel = self._model.Relationship(f"{{dst:{self._NodeConceptStr}}} has inneighbor {{src:{self._NodeConceptStr}}}")
         src, dst = self.Node.ref(), self.Node.ref()
 
@@ -1657,7 +1803,7 @@ class Graph():
             # have an edge to the destination nodes in our subset.
             where(
                 self._edge(src, dst),
-                *([nodes_subset(dst)] if nodes_subset else [])
+                *([node_subset(dst)] if node_subset else [])
             ).define(
                 _inneighbor_rel(dst, src)
             )
@@ -1666,7 +1812,7 @@ class Graph():
             # so neighbors and in-neighbors are the same.
             where(
                 self._edge(src, dst),
-                *([nodes_subset(dst)] if nodes_subset else [])
+                *([node_subset(dst)] if node_subset else [])
             ).define(
                 _inneighbor_rel(dst, src)
             )
@@ -1783,27 +1929,27 @@ class Graph():
             return self._outneighbor
         else:
             # Validate the 'of' parameter
-            self._validate_node_subset_parameter(of)
+            self._validate_node_subset_parameter('of', of)
             return self._outneighbor_of(of)
 
     @cached_property
     def _outneighbor(self):
         """Lazily define and cache the self._outneighbor relationship."""
-        _outneighbor_rel = self._create_outneighbor_relationship(nodes_subset=None)
+        _outneighbor_rel = self._create_outneighbor_relationship(node_subset=None)
         _outneighbor_rel.annotate(annotations.track("graphs", "outneighbor"))
         return _outneighbor_rel
 
-    def _outneighbor_of(self, nodes_subset: Relationship):
+    def _outneighbor_of(self, node_subset: Relationship):
         """
         Create an outneighbor relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        _outneighbor_rel = self._create_outneighbor_relationship(nodes_subset=nodes_subset)
+        _outneighbor_rel = self._create_outneighbor_relationship(node_subset=node_subset)
         _outneighbor_rel.annotate(annotations.track("graphs", "outneighbor_of"))
         return _outneighbor_rel
 
-    def _create_outneighbor_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_outneighbor_relationship(self, *, node_subset: Optional[Relationship]):
         _outneighbor_rel = self._model.Relationship(f"{{src:{self._NodeConceptStr}}} has outneighbor {{dst:{self._NodeConceptStr}}}")
         src, dst = self.Node.ref(), self.Node.ref()
 
@@ -1812,7 +1958,7 @@ class Graph():
             # have an edge from the source nodes in our subset.
             where(
                 self._edge(src, dst),
-                *([nodes_subset(src)] if nodes_subset else [])
+                *([node_subset(src)] if node_subset else [])
             ).define(
                 _outneighbor_rel(src, dst)
             )
@@ -1821,7 +1967,7 @@ class Graph():
             # so neighbors and out-neighbors are the same.
             where(
                 self._edge(src, dst),
-                *([nodes_subset(src)] if nodes_subset else [])
+                *([node_subset(src)] if node_subset else [])
             ).define(
                 _outneighbor_rel(src, dst)
             )
@@ -1830,18 +1976,67 @@ class Graph():
 
 
     @include_in_docs
-    def common_neighbor(self):
-        """Returns a ternary relationship of all common neighbor triplets.
+    def common_neighbor(self,
+            *,
+            full: Optional[bool] = None,
+            from_: Optional[Relationship] = None,
+            to: Optional[Relationship] = None,
+            between: Optional[Relationship] = None,
+        ):
+        """Returns a ternary relationship of common neighbor triplets.
 
         A node `w` is a common neighbor of a pair of nodes `u` and `v` if
         `w` is a neighbor of both `u` and `v`.
 
+        Parameters
+        ----------
+        full : bool, optional
+            If ``True``, computes common neighbors for all pairs of nodes in
+            the graph. This computation can be expensive for large graphs, as the
+            result can scale quadratically in the number of edges or cubically in
+            the number of nodes. Mutually exclusive with other parameters.
+            Default is ``None``.
+        from_ : Relationship, optional
+            A unary relationship containing a subset of the graph's nodes. When
+            provided, constrains the domain of the common neighbor computation: only
+            common neighbors of node pairs where the first node is in this relationship
+            are computed and returned. Mutually exclusive with ``full`` and ``between``.
+            Default is ``None``.
+        to : Relationship, optional
+            A unary relationship containing a subset of the graph's nodes. Can only
+            be used together with the ``from_`` parameter. When provided with ``from_``,
+            constrains the domain of the common neighbor computation: only common
+            neighbors of node pairs where the first node is in ``from_`` and the
+            second node is in ``to`` are computed and returned.
+            Default is ``None``.
+        between : Relationship, optional
+            A binary relationship containing pairs of nodes. When provided,
+            constrains the domain of the common neighbor computation: only common
+            neighbors for the specific node pairs in this relationship are computed
+            and returned. Mutually exclusive with other parameters.
+            Default is ``None``.
+
         Returns
         -------
         Relationship
             A ternary relationship where each tuple represents a pair of nodes
             and one of their common neighbors.
 
+        Raises
+        ------
+        ValueError
+            If ``full`` is provided with any other parameter.
+            If ``between`` is provided with any other parameter.
+            If ``from_`` is provided with any parameter other than ``to``.
+            If none of ``full``, ``from_``, or ``between`` is provided.
+            If ``full`` is not ``True`` or ``None``.
+        AssertionError
+            If ``from_``, ``to``, or ``between`` is not a ``Relationship``.
+            If ``from_``, ``to``, or ``between`` is not attached to the same model as the graph.
+            If ``from_``, ``to``, or ``between`` does not contain the graph's ``Node`` concept.
+            If ``from_`` or ``to`` is not a unary relationship.
+            If ``between`` is not a binary relationship.
+
         Relationship Schema
         -------------------
         ``common_neighbor(node_u, node_v, common_neighbor_node)``
@@ -1858,6 +2053,37 @@ class Graph():
         | Directed   | Yes       |                      |
         | Weighted   | Yes       | Weights are ignored. |
 
+        Notes
+        -----
+        The ``common_neighbor(full=True)`` method computes and caches the full common
+        neighbor relationship for all pairs of nodes, providing efficient reuse across
+        multiple calls. This can be expensive as the result can contain O(|E|²) or
+        O(|V|³) tuples depending on graph density.
+
+        Calling ``common_neighbor()`` without arguments raises a ``ValueError``,
+        to ensure awareness and explicit acknowledgement (``full=True``) of this cost.
+
+        In contrast, ``common_neighbor(from_=subset)`` constrains the computation to
+        tuples with the first position in the passed-in ``subset``. The result is
+        not cached; it is specific to the call site. When a significant fraction of
+        the common neighbor relation is needed across a program, ``common_neighbor(full=True)``
+        is typically more efficient. Use ``common_neighbor(from_=subset)`` only
+        when small subsets of the common neighbor relationship are needed
+        collectively across the program.
+
+        The ``to`` parameter can be used together with ``from_`` to further
+        constrain the computation: ``common_neighbor(from_=subset_a, to=subset_b)``
+        computes common neighbors only for node pairs where the first node is in
+        ``subset_a`` and the second node is in ``subset_b``. (Since ``common_neighbor``
+        is symmetric in its first two positions, using ``to`` without ``from_`` would
+        be functionally redundant, and is not allowed.)
+
+        The ``between`` parameter provides another way to constrain the computation:
+        Unlike ``from_`` and ``to``, which allow you to independently constrain the first
+        and second positions in ``common_neighbor`` tuples to sets of nodes, ``between``
+        allows you to constrain the first and second positions, jointly, to specific pairs
+        of nodes.
+
         Examples
         --------
         >>> from relationalai.semantics import Model, define, select
@@ -1881,7 +2107,7 @@ class Graph():
         >>>
         >>> # 3. Select the IDs from the common_neighbor relationship and inspect
         >>> u, v, w = Node.ref("u"), Node.ref("v"), Node.ref("w")
-        >>> common_neighbor = graph.common_neighbor()
+        >>> common_neighbor = graph.common_neighbor(full=True)
         >>> select(
         ...     u.id, v.id, w.id
         ... ).where(
@@ -1913,27 +2139,230 @@ class Graph():
         21   4    4    2
         22   4    4    3
 
+        >>> # 4. Use 'from_' parameter to constrain the set of nodes to compute common neighbors for
+        >>> # Define a subset containing only node 1
+        >>> subset = model.Relationship(f"{{node:{Node}}} is in subset")
+        >>> node = Node.ref()
+        >>> where(node.id == 1).define(subset(node))
+        >>>
+        >>> # Get common neighbors only for pairs where first node is in subset
+        >>> constrained_common_neighbor = graph.common_neighbor(from_=subset)
+        >>> select(u.id, v.id, w.id).where(constrained_common_neighbor(u, v, w)).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2  id3
+        0   1    1    2
+        1   1    3    2
+        2   1    4    2
+
+        >>> # 5. Use both 'from_' and 'to' parameters to constrain the first two positions
+        >>> subset_a = model.Relationship(f"{{node:{Node}}} is in subset_a")
+        >>> subset_b = model.Relationship(f"{{node:{Node}}} is in subset_b")
+        >>> where(node.id == 1).define(subset_a(node))
+        >>> where(node.id == 3).define(subset_b(node))
+        >>>
+        >>> # Get common neighbors only where the first node is in subset_a and the second node is in subset_b
+        >>> constrained_common_neighbor = graph.common_neighbor(from_=subset_a, to=subset_b)
+        >>> select(u.id, v.id, w.id).where(constrained_common_neighbor(u, v, w)).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2  id3
+        0   1    3    2
+
+        >>> # 6. Use 'between' parameter to constrain to specific pairs of nodes
+        >>> pairs = model.Relationship(f"{{node_a:{Node}}} and {{node_b:{Node}}} are a pair")
+        >>> node_a, node_b = Node.ref(), Node.ref()
+        >>> where(node_a.id == 1, node_b.id == 3).define(pairs(node_a, node_b))
+        >>> where(node_a.id == 2, node_b.id == 4).define(pairs(node_a, node_b))
+        >>>
+        >>> # Get common neighbors only for the specific pairs (1, 3) and (2, 4)
+        >>> constrained_common_neighbor = graph.common_neighbor(between=pairs)
+        >>> select(u.id, v.id, w.id).where(constrained_common_neighbor(u, v, w)).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2  id3
+        0   1    3    2
+        1   2    4    3
+
         """
-        warnings.warn(
-            (
-                "`common_neighbor` presently always computes common neighbors "
-                "for all pairs of nodes in the graph. To provide better control "
-                "over the computed subset, `common_neighbor`'s interface "
-                "will soon need to change."
-            ),
-            FutureWarning,
-            stacklevel=2
+        # Validate domain constraint parameters.
+        self._validate_domain_constraint_parameters(
+            'common_neighbor', full, from_, to, between
         )
+
+        # At this point, exactly one of `full`, `from_`, or `between`
+        # has been provided, and if `to` is provided, `from_` is also provided.
+
+        # Handle `between`.
+        if between is not None:
+            self._validate_pair_subset_parameter(between)
+            return self._common_neighbor_between(between)
+
+        # Handle `from_` (and potentially `to`).
+        if from_ is not None:
+            self._validate_node_subset_parameter('from_', from_)
+            if to is not None:
+                self._validate_node_subset_parameter('to', to)
+                return self._common_neighbor_from_to(from_, to)
+            return self._common_neighbor_from(from_)
+
+        # Handle `full`.
         return self._common_neighbor
 
     @cached_property
     def _common_neighbor(self):
-        """Lazily define and cache the self._common_neighbor relationship."""
-        _common_neighbor_rel = self._model.Relationship(f"{{node_a:{self._NodeConceptStr}}} and {{node_b:{self._NodeConceptStr}}} have common neighbor {{node_c:{self._NodeConceptStr}}}")
+        """Lazily define and cache the full common_neighbor relationship."""
+        _common_neighbor_rel = self._create_common_neighbor_relationship()
         _common_neighbor_rel.annotate(annotations.track("graphs", "common_neighbor"))
+        return _common_neighbor_rel
+
+    def _common_neighbor_from(self, node_subset_from: Relationship):
+        """
+        Create a common_neighbor relationship, with the first position in each
+        tuple constrained to be in the given subset of nodes. Note this relationship
+        is not cached; it is specific to the callsite.
+        """
+        _common_neighbor_rel = self._create_common_neighbor_relationship(
+            node_subset_from=node_subset_from
+        )
+        _common_neighbor_rel.annotate(annotations.track("graphs", "common_neighbor_from"))
+        return _common_neighbor_rel
+
+    def _common_neighbor_from_to(self, node_subset_from: Relationship, node_subset_to: Relationship):
+        """
+        Create a common_neighbor relationship, with the first position in each
+        tuple constrained to be in `node_subset_from`, and the second position in
+        each tuple constrained to be in `node_subset_to`. Note this relationship
+        is not cached; it is specific to the callsite.
+        """
+        _common_neighbor_rel = self._create_common_neighbor_relationship(
+            node_subset_from=node_subset_from,
+            node_subset_to=node_subset_to
+        )
+        _common_neighbor_rel.annotate(annotations.track("graphs", "common_neighbor_from_to"))
+        return _common_neighbor_rel
+
+    def _common_neighbor_between(self, pair_subset: Relationship):
+        """
+        Create a common_neighbor relationship, with the first and second position
+        in each tuple jointly constrained to be in the given set of pairs
+        of nodes. Note this relationship is not cached;
+        it is specific to the callsite.
+        """
+        _common_neighbor_rel = self._create_common_neighbor_relationship(
+            pair_subset_between=pair_subset
+        )
+        _common_neighbor_rel.annotate(annotations.track("graphs", "common_neighbor_between"))
+        return _common_neighbor_rel
+
+    def _create_common_neighbor_relationship(
+        self,
+        *,
+        node_subset_from: Optional[Relationship] = None,
+        node_subset_to: Optional[Relationship] = None,
+        pair_subset_between: Optional[Relationship] = None,
+    ):
+        """
+        Create common_neighbor relationship, optionally constrained by the provided
+        node subsets or pair subset.
+        """
+        _common_neighbor_rel = self._model.Relationship(
+            f"{{node_a:{self._NodeConceptStr}}} and {{node_b:{self._NodeConceptStr}}} "
+            f"have common neighbor {{neighbor_node:{self._NodeConceptStr}}}"
+        )
+        node_a, node_b, neighbor_node = self.Node.ref(), self.Node.ref(), self.Node.ref()
+
+        # Handle the `between` case.
+        if pair_subset_between is not None:
+            # Extract all nodes that appear in any position of the pairs relationship
+            # into a unary relation that we can use to constrain the neighbor computation.
+            nodes_in_pairs = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} is in pairs subset")
+            node_x, node_y = self.Node.ref(), self.Node.ref()
+            where(
+                pair_subset_between(node_x, node_y)
+            ).define(
+                nodes_in_pairs(node_x),
+                nodes_in_pairs(node_y)
+            )
+
+            # Create a neighbor relation constrained to the nodes that appear in the pairs.
+            neighbor_rel = self._neighbor_of(nodes_in_pairs)
+            neighbor_a_rel = neighbor_rel
+            neighbor_b_rel = neighbor_rel
+
+            # The constraint fragment ensures we only compute common neighbors for the
+            # specific pairs provided, not for all combinations of nodes in those pairs.
+            node_constraint = [pair_subset_between(node_a, node_b)]
+
+        # Handle the `from_` case.
+        elif node_subset_from is not None and node_subset_to is None:
+            # Note that in this case we must compute all of `_neighbor` anyway,
+            # as the second position in each tuple is unconstrained. Given that,
+            # computing `_neighbor_of` for `node_subset_from` to constrain the
+            # first position that way would be less efficient than using
+            # `_neighbor` and joining the relevant variable with `node_subset_from`.
+            neighbor_a_rel = self._neighbor
+            neighbor_b_rel = self._neighbor
+            node_constraint = [node_subset_from(node_a)]
+            # TODO: Nice observation from @rygao: We can instead implement this
+            #   as a depth-2 traversal starting from `node_subset_from`. Candidate code:
+
+                # neighbor_a_rel = self._neighbor_of(node_subset_from)
+                #
+                # domain_w = Relationship(f"{{node:{self._NodeConceptStr}}} is the domain of `w` in `common_neighbor(u, v, w)`")
+                # node_x, node_y = graph.Node.ref(), graph.Node.ref()
+                # where(neighbor_a_rel(node_x, node_y)).define(domain_w(node_y))
+                # neighbor_b_rel = self._neighbor_of(domain_w)
+                #
+                # node_constraint = []
+                #
+                # # need to reverse the args of `neighbor_b_rel()`, due to its domain constraint
+                # # relies on the symmetry of `neighbor`
+                # where(
+                #     *node_constraint,
+                #     neighbor_a_rel(node_a, neighbor_node),
+                #     neighbor_b_rel(neighbor_node, node_b)
+                # ).define(_common_neighbor_rel(node_a, node_b, neighbor_node))
+
+        # Handle the `from_`/`to` case.
+        elif node_subset_from is not None and node_subset_to is not None:
+            # There are two cases:
+            #
+            # NOTE: For both of the following branches, spiritually we are applying
+            #   `node_constraint = [node_subset_from(node_a), node_subset_to(node_b)]`,
+            #   but these are already enforced by the use of the constrained
+            #   `_neighbor_of` relationships, so we don't need to include them
+            #   again in `node_constraint`.
+            if node_subset_from is node_subset_to:
+                # If `node_subset_from` and `node_subset_to` are object-identical,
+                # we can compute `_neighbor_of` once, use it for both positions,
+                # and apply no further constraint.
+                neighbor_rel = self._neighbor_of(node_subset_from)
+                neighbor_a_rel = neighbor_rel
+                neighbor_b_rel = neighbor_rel
+                node_constraint = []
+            else:
+                # Otherwise, we have two options: 1) compute `_neighbor_of` twice,
+                # once for each node subset; or 2) compute `_neighbor` once, over
+                # the union of both subsets, and apply constraints to each position.
+                # Which of these is more efficient depends on the detailed nature
+                # of the subsets, which we don't have knowledge of here. Here
+                # we choose the simpler/cleaner of the two options (1) as such:
+                neighbor_a_rel = self._neighbor_of(node_subset_from)
+                neighbor_b_rel = self._neighbor_of(node_subset_to)
+                node_constraint = []
+
+        # Handle the `full` case.
+        else:
+            neighbor_a_rel = self._neighbor
+            neighbor_b_rel = self._neighbor
+            node_constraint = []
+
+        # Define the common neighbor relationship using the neighbor relations and
+        # constraints determined above. This logic is shared across all constraint types.
+        where(
+            *node_constraint,
+            neighbor_a_rel(node_a, neighbor_node),
+            neighbor_b_rel(node_b, neighbor_node)
+        ).define(_common_neighbor_rel(node_a, node_b, neighbor_node))
 
-        node_a, node_b, node_c = self.Node.ref(), self.Node.ref(), self.Node.ref()
-        where(self._neighbor(node_a, node_c), self._neighbor(node_b, node_c)).define(_common_neighbor_rel(node_a, node_b, node_c))
         return _common_neighbor_rel
 
 
@@ -2084,37 +2513,37 @@ class Graph():
             return self._degree
         else:
             # Validate the 'of' parameter
-            self._validate_node_subset_parameter(of)
+            self._validate_node_subset_parameter('of', of)
             return self._degree_of(of)
 
     @cached_property
     def _degree(self):
         """Lazily define and cache the self._degree relationship."""
-        _degree_rel = self._create_degree_relationship(nodes_subset=None)
+        _degree_rel = self._create_degree_relationship(node_subset=None)
         _degree_rel.annotate(annotations.track("graphs", "degree"))
         return _degree_rel
 
-    def _degree_of(self, nodes_subset: Relationship):
+    def _degree_of(self, node_subset: Relationship):
         """
         Create a degree relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        _degree_rel = self._create_degree_relationship(nodes_subset=nodes_subset)
+        _degree_rel = self._create_degree_relationship(node_subset=node_subset)
         _degree_rel.annotate(annotations.track("graphs", "degree_of"))
         return _degree_rel
 
-    def _create_degree_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_degree_relationship(self, *, node_subset: Optional[Relationship]):
         _degree_rel = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} has degree {{count:Integer}}")
 
         if self.directed:
             # For directed graphs, degree is the sum of indegree and outdegree.
-            if nodes_subset is None:
+            if node_subset is None:
                 indegree_rel = self._indegree
                 outdegree_rel = self._outdegree
             else:
-                indegree_rel = self._indegree_of(nodes_subset)
-                outdegree_rel = self._outdegree_of(nodes_subset)
+                indegree_rel = self._indegree_of(node_subset)
+                outdegree_rel = self._outdegree_of(node_subset)
 
             incount, outcount = Integer.ref(), Integer.ref()
             where(
@@ -2123,12 +2552,12 @@ class Graph():
             ).define(_degree_rel(self.Node, incount + outcount))
         else:
             # For undirected graphs, degree is the count of neighbors.
-            if nodes_subset is None:
+            if node_subset is None:
                 node_set = self.Node
                 count_neighbor_rel = self._count_neighbor
             else:
-                node_set = nodes_subset
-                count_neighbor_rel = self._count_neighbor_of(nodes_subset)
+                node_set = node_subset
+                count_neighbor_rel = self._count_neighbor_of(node_subset)
 
             where(
                 node_set(self.Node), # Necessary given the match on the following line.
@@ -2279,38 +2708,38 @@ class Graph():
             return self._indegree
         else:
             # Validate the 'of' parameter
-            self._validate_node_subset_parameter(of)
+            self._validate_node_subset_parameter('of', of)
             return self._indegree_of(of)
 
     @cached_property
     def _indegree(self):
         """Lazily define and cache the self._indegree relationship."""
-        _indegree_rel = self._create_indegree_relationship(nodes_subset=None)
+        _indegree_rel = self._create_indegree_relationship(node_subset=None)
         _indegree_rel.annotate(annotations.track("graphs", "indegree"))
         return _indegree_rel
 
-    def _indegree_of(self, nodes_subset: Relationship):
+    def _indegree_of(self, node_subset: Relationship):
         """
         Create an indegree relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        _indegree_rel = self._create_indegree_relationship(nodes_subset=nodes_subset)
+        _indegree_rel = self._create_indegree_relationship(node_subset=node_subset)
         _indegree_rel.annotate(annotations.track("graphs", "indegree_of"))
         return _indegree_rel
 
-    def _create_indegree_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_indegree_relationship(self, *, node_subset: Optional[Relationship]):
         _indegree_rel = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} has indegree {{count:Integer}}")
 
         # Choose the appropriate count_inneighbor relationship and node set
-        if nodes_subset is None:
+        if node_subset is None:
             # No constraint - use cached count_inneighbor relationship and all nodes
             count_inneighbor_rel = self._count_inneighbor
             node_set = self.Node
         else:
             # Constrained to nodes in the subset - use constrained count_inneighbor relationship
-            count_inneighbor_rel = self._count_inneighbor_of(nodes_subset)
-            node_set = nodes_subset
+            count_inneighbor_rel = self._count_inneighbor_of(node_subset)
+            node_set = node_subset
 
         # Apply the same indegree logic for both cases
         where(
@@ -2463,38 +2892,38 @@ class Graph():
             return self._outdegree
         else:
             # Validate the 'of' parameter
-            self._validate_node_subset_parameter(of)
+            self._validate_node_subset_parameter('of', of)
             return self._outdegree_of(of)
 
     @cached_property
     def _outdegree(self):
         """Lazily define and cache the self._outdegree relationship."""
-        _outdegree_rel = self._create_outdegree_relationship(nodes_subset=None)
+        _outdegree_rel = self._create_outdegree_relationship(node_subset=None)
         _outdegree_rel.annotate(annotations.track("graphs", "outdegree"))
         return _outdegree_rel
 
-    def _outdegree_of(self, nodes_subset: Relationship):
+    def _outdegree_of(self, node_subset: Relationship):
         """
         Create an outdegree relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        _outdegree_rel = self._create_outdegree_relationship(nodes_subset=nodes_subset)
+        _outdegree_rel = self._create_outdegree_relationship(node_subset=node_subset)
         _outdegree_rel.annotate(annotations.track("graphs", "outdegree_of"))
         return _outdegree_rel
 
-    def _create_outdegree_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_outdegree_relationship(self, *, node_subset: Optional[Relationship]):
         _outdegree_rel = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} has outdegree {{count:Integer}}")
 
         # Choose the appropriate count_outneighbor relationship and node set
-        if nodes_subset is None:
+        if node_subset is None:
             # No constraint - use cached count_outneighbor relationship and all nodes
             count_outneighbor_rel = self._count_outneighbor
             node_set = self.Node
         else:
             # Constrained to nodes in the subset - use constrained count_outneighbor relationship
-            count_outneighbor_rel = self._count_outneighbor_of(nodes_subset)
-            node_set = nodes_subset
+            count_outneighbor_rel = self._count_outneighbor_of(node_subset)
+            node_set = node_subset
 
         # Apply the same outdegree logic for both cases
         where(
@@ -2612,37 +3041,37 @@ class Graph():
             return self._weighted_degree
         else:
             # Validate the 'of' parameter
-            self._validate_node_subset_parameter(of)
+            self._validate_node_subset_parameter('of', of)
             return self._weighted_degree_of(of)
 
     @cached_property
     def _weighted_degree(self):
         """Lazily define and cache the self._weighted_degree relationship."""
-        _weighted_degree_rel = self._create_weighted_degree_relationship(nodes_subset=None)
+        _weighted_degree_rel = self._create_weighted_degree_relationship(node_subset=None)
         _weighted_degree_rel.annotate(annotations.track("graphs", "weighted_degree"))
         return _weighted_degree_rel
 
-    def _weighted_degree_of(self, nodes_subset: Relationship):
+    def _weighted_degree_of(self, node_subset: Relationship):
         """
         Create a weighted degree relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        _weighted_degree_rel = self._create_weighted_degree_relationship(nodes_subset=nodes_subset)
+        _weighted_degree_rel = self._create_weighted_degree_relationship(node_subset=node_subset)
         _weighted_degree_rel.annotate(annotations.track("graphs", "weighted_degree_of"))
         return _weighted_degree_rel
 
-    def _create_weighted_degree_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_weighted_degree_relationship(self, *, node_subset: Optional[Relationship]):
         _weighted_degree_rel = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} has weighted degree {{weight:Float}}")
 
         if self.directed:
             # For directed graphs, weighted degree is the sum of weighted indegree and weighted outdegree.
-            if nodes_subset is None:
+            if node_subset is None:
                 weighted_indegree_rel = self._weighted_indegree
                 weighted_outdegree_rel = self._weighted_outdegree
             else:
-                weighted_indegree_rel = self._weighted_indegree_of(nodes_subset)
-                weighted_outdegree_rel = self._weighted_outdegree_of(nodes_subset)
+                weighted_indegree_rel = self._weighted_indegree_of(node_subset)
+                weighted_outdegree_rel = self._weighted_outdegree_of(node_subset)
 
             inweight, outweight = Float.ref(), Float.ref()
             where(
@@ -2651,12 +3080,12 @@ class Graph():
             ).define(_weighted_degree_rel(self.Node, inweight + outweight))
         elif not self.directed:
             # Choose the appropriate node set
-            if nodes_subset is None:
+            if node_subset is None:
                 # No constraint - use all nodes
                 node_set = self.Node
             else:
                 # Constrained to nodes in the subset
-                node_set = nodes_subset
+                node_set = node_subset
 
             dst, weight = self.Node.ref(), Float.ref()
             where(
@@ -2772,36 +3201,36 @@ class Graph():
             return self._weighted_indegree
         else:
             # Validate the 'of' parameter
-            self._validate_node_subset_parameter(of)
+            self._validate_node_subset_parameter('of', of)
             return self._weighted_indegree_of(of)
 
     @cached_property
     def _weighted_indegree(self):
         """Lazily define and cache the self._weighted_indegree relationship."""
-        _weighted_indegree_rel = self._create_weighted_indegree_relationship(nodes_subset=None)
+        _weighted_indegree_rel = self._create_weighted_indegree_relationship(node_subset=None)
         _weighted_indegree_rel.annotate(annotations.track("graphs", "weighted_indegree"))
         return _weighted_indegree_rel
 
-    def _weighted_indegree_of(self, nodes_subset: Relationship):
+    def _weighted_indegree_of(self, node_subset: Relationship):
         """
         Create a weighted indegree relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        _weighted_indegree_rel = self._create_weighted_indegree_relationship(nodes_subset=nodes_subset)
+        _weighted_indegree_rel = self._create_weighted_indegree_relationship(node_subset=node_subset)
         _weighted_indegree_rel.annotate(annotations.track("graphs", "weighted_indegree_of"))
         return _weighted_indegree_rel
 
-    def _create_weighted_indegree_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_weighted_indegree_relationship(self, *, node_subset: Optional[Relationship]):
         _weighted_indegree_rel = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} has weighted indegree {{weight:Float}}")
 
         # Choose the appropriate node set
-        if nodes_subset is None:
+        if node_subset is None:
             # No constraint - use all nodes
             node_set = self.Node
         else:
             # Constrained to nodes in the subset
-            node_set = nodes_subset
+            node_set = node_subset
         # TODO: In a future cleanup pass, replace `node_set` with a `node_constraint`
         #   that replaces the `node_set(self.Node)` in the where clause below,
         #   and generates only `self.Node` (rather than `self.Node(self.Node)`)
@@ -2924,36 +3353,36 @@ class Graph():
             return self._weighted_outdegree
         else:
             # Validate the 'of' parameter
-            self._validate_node_subset_parameter(of)
+            self._validate_node_subset_parameter('of', of)
             return self._weighted_outdegree_of(of)
 
     @cached_property
     def _weighted_outdegree(self):
         """Lazily define and cache the self._weighted_outdegree relationship."""
-        _weighted_outdegree_rel = self._create_weighted_outdegree_relationship(nodes_subset=None)
+        _weighted_outdegree_rel = self._create_weighted_outdegree_relationship(node_subset=None)
         _weighted_outdegree_rel.annotate(annotations.track("graphs", "weighted_outdegree"))
         return _weighted_outdegree_rel
 
-    def _weighted_outdegree_of(self, nodes_subset: Relationship):
+    def _weighted_outdegree_of(self, node_subset: Relationship):
         """
         Create a weighted outdegree relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        _weighted_outdegree_rel = self._create_weighted_outdegree_relationship(nodes_subset=nodes_subset)
+        _weighted_outdegree_rel = self._create_weighted_outdegree_relationship(node_subset=node_subset)
         _weighted_outdegree_rel.annotate(annotations.track("graphs", "weighted_outdegree_of"))
         return _weighted_outdegree_rel
 
-    def _create_weighted_outdegree_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_weighted_outdegree_relationship(self, *, node_subset: Optional[Relationship]):
         _weighted_outdegree_rel = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} has weighted outdegree {{weight:Float}}")
 
         # Choose the appropriate node set
-        if nodes_subset is None:
+        if node_subset is None:
             # No constraint - use all nodes
             node_set = self.Node
         else:
             # Constrained to nodes in the subset
-            node_set = nodes_subset
+            node_set = node_subset
 
         # Apply the weighted outdegree logic for both cases
         dst, outweight = self.Node.ref(), Float.ref()
@@ -3103,36 +3532,36 @@ class Graph():
             return self._degree_centrality
         else:
             # Validate the 'of' parameter
-            self._validate_node_subset_parameter(of)
+            self._validate_node_subset_parameter('of', of)
             return self._degree_centrality_of(of)
 
     @cached_property
     def _degree_centrality(self):
         """Lazily define and cache the self._degree_centrality relationship."""
-        _degree_centrality_rel = self._create_degree_centrality_relationship(nodes_subset=None)
+        _degree_centrality_rel = self._create_degree_centrality_relationship(node_subset=None)
         _degree_centrality_rel.annotate(annotations.track("graphs", "degree_centrality"))
         return _degree_centrality_rel
 
-    def _degree_centrality_of(self, nodes_subset: Relationship):
+    def _degree_centrality_of(self, node_subset: Relationship):
         """
         Create a degree centrality relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        _degree_centrality_rel = self._create_degree_centrality_relationship(nodes_subset=nodes_subset)
+        _degree_centrality_rel = self._create_degree_centrality_relationship(node_subset=node_subset)
         _degree_centrality_rel.annotate(annotations.track("graphs", "degree_centrality_of"))
         return _degree_centrality_rel
 
-    def _create_degree_centrality_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_degree_centrality_relationship(self, *, node_subset: Optional[Relationship]):
         """Create a degree centrality relationship, optionally constrained to a subset of nodes."""
         _degree_centrality_rel = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} has {{degree_centrality:Float}}")
 
-        if nodes_subset is None:
+        if node_subset is None:
             degree_rel = self._degree
             node_constraint = [] # No constraint on nodes.
         else:
-            degree_rel = self._degree_of(nodes_subset)
-            node_constraint = [nodes_subset(self.Node)]  # Nodes constrained to given subset.
+            degree_rel = self._degree_of(node_subset)
+            node_constraint = [node_subset(self.Node)]  # Nodes constrained to given subset.
 
         degree = Integer.ref()
 
@@ -3154,10 +3583,10 @@ class Graph():
         # General case, i.e. with more than one node.
         if self.weighted:
             maybe_weighted_degree = Float.ref()
-            if nodes_subset is None:
+            if node_subset is None:
                 maybe_weighted_degree_rel = self._weighted_degree
             else:
-                maybe_weighted_degree_rel = self._weighted_degree_of(nodes_subset)
+                maybe_weighted_degree_rel = self._weighted_degree_of(node_subset)
         else: # not self.weighted
             maybe_weighted_degree = Integer.ref()
             maybe_weighted_degree_rel = degree_rel
@@ -4015,35 +4444,35 @@ class Graph():
 
         """
         if of is not None:
-            self._validate_node_subset_parameter(of)
+            self._validate_node_subset_parameter('of', of)
             return self._triangle_count_of(of)
         return self._triangle_count
 
     @cached_property
     def _triangle_count(self):
         """Lazily define and cache the self._triangle_count relationship."""
-        _triangle_count_rel = self._create_triangle_count_relationship(nodes_subset=None)
+        _triangle_count_rel = self._create_triangle_count_relationship(node_subset=None)
         _triangle_count_rel.annotate(annotations.track("graphs", "triangle_count"))
         return _triangle_count_rel
 
-    def _triangle_count_of(self, nodes_subset: Relationship):
+    def _triangle_count_of(self, node_subset: Relationship):
         """
         Create a triangle count relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        _triangle_count_rel = self._create_triangle_count_relationship(nodes_subset=nodes_subset)
+        _triangle_count_rel = self._create_triangle_count_relationship(node_subset=node_subset)
         _triangle_count_rel.annotate(annotations.track("graphs", "triangle_count_of"))
         return _triangle_count_rel
 
-    def _create_triangle_count_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_triangle_count_relationship(self, *, node_subset: Optional[Relationship]):
         """Create a triangle count relationship, optionally constrained to a subset of nodes."""
         _triangle_count_rel = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} belongs to {{count:Integer}} triangles")
 
-        if nodes_subset is None:
+        if node_subset is None:
             node_constraint = self.Node # No constraint on nodes.
         else:
-            node_constraint = nodes_subset(self.Node)  # Nodes constrained to given subset.
+            node_constraint = node_subset(self.Node)  # Nodes constrained to given subset.
 
         where(
             node_constraint,
@@ -4293,41 +4722,41 @@ class Graph():
             )
 
         if of is not None:
-            self._validate_node_subset_parameter(of)
+            self._validate_node_subset_parameter('of', of)
             return self._local_clustering_coefficient_of(of)
         return self._local_clustering_coefficient
 
     @cached_property
     def _local_clustering_coefficient(self):
         """Lazily define and cache the self._local_clustering_coefficient relationship."""
-        _local_clustering_coefficient_rel = self._create_local_clustering_coefficient_relationship(nodes_subset=None)
+        _local_clustering_coefficient_rel = self._create_local_clustering_coefficient_relationship(node_subset=None)
         _local_clustering_coefficient_rel.annotate(annotations.track("graphs", "local_clustering_coefficient"))
         return _local_clustering_coefficient_rel
 
-    def _local_clustering_coefficient_of(self, nodes_subset: Relationship):
+    def _local_clustering_coefficient_of(self, node_subset: Relationship):
         """
         Create a local clustering coefficient relationship constrained to the subset of nodes
-        in `nodes_subset`. Note this relationship is not cached; it is
+        in `node_subset`. Note this relationship is not cached; it is
         specific to the callsite.
         """
-        _local_clustering_coefficient_rel = self._create_local_clustering_coefficient_relationship(nodes_subset=nodes_subset)
+        _local_clustering_coefficient_rel = self._create_local_clustering_coefficient_relationship(node_subset=node_subset)
         _local_clustering_coefficient_rel.annotate(annotations.track("graphs", "local_clustering_coefficient_of"))
         return _local_clustering_coefficient_rel
 
-    def _create_local_clustering_coefficient_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_local_clustering_coefficient_relationship(self, *, node_subset: Optional[Relationship]):
         """Create a local clustering coefficient relationship, optionally constrained to a subset of nodes."""
         _local_clustering_coefficient_rel = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} has local clustering coefficient {{coefficient:Float}}")
 
         node = self.Node.ref()
 
-        if nodes_subset is None:
+        if node_subset is None:
             degree_no_self_rel = self._degree_no_self
             triangle_count_rel = self._triangle_count
             node_constraint = node  # No constraint on nodes.
         else:
-            degree_no_self_rel = self._degree_no_self_of(nodes_subset)
-            triangle_count_rel = self._triangle_count_of(nodes_subset)
-            node_constraint = nodes_subset(node)  # Nodes constrained to given subset.
+            degree_no_self_rel = self._degree_no_self_of(node_subset)
+            triangle_count_rel = self._triangle_count_of(node_subset)
+            node_constraint = node_subset(node)  # Nodes constrained to given subset.
 
         degree_no_self = Integer.ref()
         triangle_count = Integer.ref()
@@ -4350,17 +4779,17 @@ class Graph():
         Lazily define and cache the self._degree_no_self relationship,
         a non-public helper for local_clustering_coefficient.
         """
-        return self._create_degree_no_self_relationship(nodes_subset=None)
+        return self._create_degree_no_self_relationship(node_subset=None)
 
-    def _degree_no_self_of(self, nodes_subset: Relationship):
+    def _degree_no_self_of(self, node_subset: Relationship):
         """
         Create a self-loop-exclusive degree relationship constrained to
-        the subset of nodes in `nodes_subset`. Note this relationship
+        the subset of nodes in `node_subset`. Note this relationship
         is not cached; it is specific to the callsite.
         """
-        return self._create_degree_no_self_relationship(nodes_subset=nodes_subset)
+        return self._create_degree_no_self_relationship(node_subset=node_subset)
 
-    def _create_degree_no_self_relationship(self, *, nodes_subset: Optional[Relationship]):
+    def _create_degree_no_self_relationship(self, *, node_subset: Optional[Relationship]):
         """
         Create a self-loop-exclusive degree relationship,
         optionally constrained to a subset of nodes.
@@ -4369,10 +4798,10 @@ class Graph():
 
         node, neighbor = self.Node.ref(), self.Node.ref()
 
-        if nodes_subset is None:
+        if node_subset is None:
             node_constraint = node  # No constraint on nodes.
         else:
-            node_constraint = nodes_subset(node)  # Nodes constrained to given subset.
+            node_constraint = node_subset(node)  # Nodes constrained to given subset.
 
         where(
             node_constraint,
@@ -5417,19 +5846,72 @@ class Graph():
 
 
     @include_in_docs
-    def cosine_similarity(self):
-        """Returns a ternary relationship containing the cosine similarity for all pairs of nodes.
+    def cosine_similarity(
+            self,
+            *,
+            full: Optional[bool] = None,
+            from_: Optional[Relationship] = None,
+            to: Optional[Relationship] = None,
+            between: Optional[Relationship] = None,
+        ):
+        """Returns a ternary relationship containing
+        the cosine similarity for pairs of nodes.
 
         The cosine similarity measures the similarity between two nodes based
         on the angle between their neighborhood vectors. The score ranges from
         0.0 to 1.0, inclusive, where 1.0 indicates identical sets of neighbors.
 
+        Parameters
+        ----------
+        full : bool, optional
+            If ``True``, computes the cosine similarity for all pairs
+            of nodes in the graph. This computation can be expensive for large graphs,
+            as the result can scale quadratically in the number of nodes. Mutually exclusive
+            with other parameters.
+            Default is ``None``.
+        from_ : Relationship, optional
+            A unary relationship containing a subset of the graph's nodes. When
+            provided, constrains the domain of the cosine similarity computation: only
+            cosine similarity scores for node pairs where the first node is
+            in this relationship are computed and returned. Mutually exclusive with
+            ``full`` and ``between``.
+            Default is ``None``.
+        to : Relationship, optional
+            A unary relationship containing a subset of the graph's nodes. Can only
+            be used together with the ``from_`` parameter. When provided with ``from_``,
+            constrains the domain of the cosine similarity computation: only
+            cosine similarity scores for node pairs where the first node is
+            in ``from_`` and the second node is in ``to`` are computed and returned.
+            Default is ``None``.
+        between : Relationship, optional
+            A binary relationship containing pairs of nodes. When provided,
+            constrains the domain of the cosine similarity computation: only
+            cosine similarity scores for the specific node pairs in
+            this relationship are computed and returned. Mutually exclusive
+            with other parameters.
+            Default is ``None``.
+
         Returns
         -------
         Relationship
             A ternary relationship where each tuple represents a pair of nodes
             and their cosine similarity.
 
+        Raises
+        ------
+        ValueError
+            If ``full`` is provided with any other parameter.
+            If ``between`` is provided with any other parameter.
+            If ``from_`` is provided with any parameter other than ``to``.
+            If none of ``full``, ``from_``, or ``between`` is provided.
+            If ``full`` is not ``True`` or ``None``.
+        AssertionError
+            If ``from_``, ``to``, or ``between`` is not a ``Relationship``.
+            If ``from_``, ``to``, or ``between`` is not attached to the same model as the graph.
+            If ``from_``, ``to``, or ``between`` does not contain the graph's ``Node`` concept.
+            If ``from_`` or ``to`` is not a unary relationship.
+            If ``between`` is not a binary relationship.
+
         Relationship Schema
         -------------------
         ``cosine_similarity(node_u, node_v, score)``
@@ -5462,6 +5944,36 @@ class Graph():
         vectors contain only non-negative elements. Therefore, the cosine
         similarity score is always between 0.0 and 1.0, inclusive.
 
+        The ``cosine_similarity(full=True)`` method computes and caches
+        the full cosine similarity relationship for all pairs of nodes,
+        providing efficient reuse across multiple calls. This can be expensive
+        as the result can contain O(|V|²) tuples.
+
+        Calling ``cosine_similarity()`` without arguments raises a ``ValueError``,
+        to ensure awareness and explicit acknowledgement (``full=True``) of this cost.
+
+        In contrast, ``cosine_similarity(from_=subset)`` constrains the computation to
+        tuples with the first position in the passed-in ``subset``. The result is
+        not cached; it is specific to the call site. When a significant fraction of
+        the cosine similarity relation is needed across a program,
+        ``cosine_similarity(full=True)`` is typically more efficient. Use
+        ``cosine_similarity(from_=subset)`` only when small subsets of
+        the cosine similarity relationship are needed
+        collectively across the program.
+
+        The ``to`` parameter can be used together with ``from_`` to further
+        constrain the computation: ``cosine_similarity(from_=subset_a, to=subset_b)``
+        computes cosine similarity scores only for node pairs where the first node is in
+        ``subset_a`` and the second node is in ``subset_b``. (Since ``cosine_similarity``
+        is symmetric in its first two positions, using ``to`` without ``from_`` would
+        be functionally redundant, and is not allowed.)
+
+        The ``between`` parameter provides another way to constrain the computation.
+        Unlike ``from_`` and ``to``, which allow you to independently constrain the first
+        and second positions in ``cosine_similarity`` tuples to sets of nodes, ``between``
+        allows you constrain the first and second positions, jointly, to specific pairs
+        of nodes.
+
         Examples
         --------
         **Unweighted Graph Examples**
@@ -5483,7 +5995,7 @@ class Graph():
         ...     Edge.new(src=n4, dst=n3),
         ... )
         >>> u, v, score = Node.ref("u"), Node.ref("v"), Float.ref("score")
-        >>> cosine_similarity = graph.cosine_similarity()
+        >>> cosine_similarity = graph.cosine_similarity(full=True)
         >>> select(score).where(cosine_similarity(u, v, score), u.id == 2, v.id == 4).inspect()
         ▰▰▰▰ Setup complete
               score
@@ -5506,7 +6018,7 @@ class Graph():
         ...     Edge.new(src=n4, dst=n3),
         ... )
         >>> u, v, score = Node.ref("u"), Node.ref("v"), Float.ref("score")
-        >>> cosine_similarity = graph.cosine_similarity()
+        >>> cosine_similarity = graph.cosine_similarity(full=True)
         >>> select(score).where(cosine_similarity(u, v, score), u.id == 2, v.id == 4).inspect()
         ▰▰▰▰ Setup complete
               score
@@ -5531,7 +6043,7 @@ class Graph():
         ...     Edge.new(src=n14, dst=n13, weight=1.0),
         ... )
         >>> u, v, score = Node.ref("u"), Node.ref("v"), Float.ref("score")
-        >>> cosine_similarity = graph.cosine_similarity()
+        >>> cosine_similarity = graph.cosine_similarity(full=True)
         >>> select(score).where(cosine_similarity(u, v, score), u.id == 1, v.id == 2).inspect()
         ▰▰▰▰ Setup complete
               score
@@ -5553,49 +6065,246 @@ class Graph():
         ...     Edge.new(src=n2, dst=n4, weight=5.0),
         ... )
         >>> u, v, score = Node.ref("u"), Node.ref("v"), Float.ref("score")
-        >>> cosine_similarity = graph.cosine_similarity()
+        >>> cosine_similarity = graph.cosine_similarity(full=True)
         >>> select(score).where(cosine_similarity(u, v, score), u.id == 1, v.id == 2).inspect()
         ▰▰▰▰ Setup complete
               score
         0  0.996241
 
+        **Domain Constraint Examples**
+
+        >>> # Use 'from_' parameter to constrain the set of nodes for the first position
+        >>> # Using the same undirected unweighted graph from above
+        >>> from relationalai.semantics import where
+        >>> subset = model.Relationship(f"{{node:{Node}}} is in subset")
+        >>> node = Node.ref()
+        >>> where(node.id == 2).define(subset(node))
+        >>>
+        >>> # Get cosine similarity scores only for pairs where first node is in subset
+        >>> constrained_cosine_similarity = graph.cosine_similarity(from_=subset)
+        >>> select(u.id, v.id, score).where(constrained_cosine_similarity(u, v, score)).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2     score
+        0   2    2  1.000000
+        1   2    3  0.707107
+        2   2    4  0.408248
+
+        >>> # Use both 'from_' and 'to' parameters to constrain both positions
+        >>> from_subset = model.Relationship(f"{{node:{Node}}} is in from_subset")
+        >>> to_subset = model.Relationship(f"{{node:{Node}}} is in to_subset")
+        >>> where(node.id == 2).define(from_subset(node))
+        >>> where(node.id == 4).define(to_subset(node))
+        >>>
+        >>> # Get cosine similarity scores only where first node is in from_subset and second node is in to_subset
+        >>> constrained_cosine_similarity = graph.cosine_similarity(from_=from_subset, to=to_subset)
+        >>> select(u.id, v.id, score).where(constrained_cosine_similarity(u, v, score)).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2     score
+        0   2    4  0.408248
+
+        >>> # Use 'between' parameter to constrain to specific pairs of nodes
+        >>> pairs = model.Relationship(f"{{node_a:{Node}}} and {{node_b:{Node}}} are a pair")
+        >>> node_a, node_b = Node.ref(), Node.ref()
+        >>> where(node_a.id == 2, node_b.id == 4).define(pairs(node_a, node_b))
+        >>> where(node_a.id == 3, node_b.id == 4).define(pairs(node_a, node_b))
+        >>>
+        >>> # Get cosine similarity scores only for the specific pairs (2, 4) and (3, 4)
+        >>> constrained_cosine_similarity = graph.cosine_similarity(between=pairs)
+        >>> select(u.id, v.id, score).where(constrained_cosine_similarity(u, v, score)).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2     score
+        0   2    4  0.408248
+        1   3    4  0.707107
+
         """
-        warnings.warn(
-            (
-                "`cosine_similarity` presently always computes the similarity "
-                "of all pairs of nodes of the graph. To provide better control over "
-                "the computed subset, `cosine_similarity`'s interface will soon "
-                "need to change."
-            ),
-            FutureWarning,
-            stacklevel=2
+        # Validate domain constraint parameters.
+        self._validate_domain_constraint_parameters(
+            'cosine_similarity', full, from_, to, between
         )
 
+        # At this point, exactly one of `full`, `from_`, or `between`
+        # has been provided, and if `to` is provided, `from_` is also provided.
+
+        # Handle `between`.
+        if between is not None:
+            self._validate_pair_subset_parameter(between)
+            return self._cosine_similarity_between(between)
+
+        # Handle `from_` (and potentially `to`).
+        if from_ is not None:
+            self._validate_node_subset_parameter('from_', from_)
+            if to is not None:
+                self._validate_node_subset_parameter('to', to)
+                return self._cosine_similarity_from_to(from_, to)
+            return self._cosine_similarity_from(from_)
+
+        # Handle `full`.
         return self._cosine_similarity
 
     @cached_property
     def _cosine_similarity(self):
-        """Lazily define and cache the self._cosine_similarity relationship."""
-        _cosine_similarity_rel = self._model.Relationship(f"{{node_u:{self._NodeConceptStr}}} has a cosine similarity to {{node_v:{self._NodeConceptStr}}} of {{score:Float}}")
+        """Lazily define and cache the full cosine_similarity relationship."""
+        _cosine_similarity_rel = self._create_cosine_similarity_relationship()
         _cosine_similarity_rel.annotate(annotations.track("graphs", "cosine_similarity"))
+        return _cosine_similarity_rel
 
+    def _cosine_similarity_from(self, node_subset_from: Relationship):
+        """
+        Create a cosine_similarity relationship, with the first position in each
+        tuple constrained to be in the given subset of nodes. Note this relationship
+        is not cached; it is specific to the callsite.
+        """
+        _cosine_similarity_rel = self._create_cosine_similarity_relationship(
+            node_subset_from=node_subset_from
+        )
+        _cosine_similarity_rel.annotate(annotations.track("graphs", "cosine_similarity_from"))
+        return _cosine_similarity_rel
+
+    def _cosine_similarity_from_to(self, node_subset_from: Relationship, node_subset_to: Relationship):
+        """
+        Create a cosine_similarity relationship, with the first position in each
+        tuple constrained to be in `node_subset_from`, and the second position in
+        each tuple constrained to be in `node_subset_to`. Note this relationship
+        is not cached; it is specific to the callsite.
+        """
+        _cosine_similarity_rel = self._create_cosine_similarity_relationship(
+            node_subset_from=node_subset_from,
+            node_subset_to=node_subset_to
+        )
+        _cosine_similarity_rel.annotate(annotations.track("graphs", "cosine_similarity_from_to"))
+        return _cosine_similarity_rel
+
+    def _cosine_similarity_between(self, pair_subset_between: Relationship):
+        """
+        Create a cosine_similarity relationship, with the first and second position
+        in each tuple jointly constrained to be in the given set of pairs
+        of nodes. Note this relationship is not cached;
+        it is specific to the callsite.
+        """
+        _cosine_similarity_rel = self._create_cosine_similarity_relationship(
+            pair_subset_between=pair_subset_between
+        )
+        _cosine_similarity_rel.annotate(annotations.track("graphs", "cosine_similarity_between"))
+        return _cosine_similarity_rel
+
+    def _create_cosine_similarity_relationship(
+        self,
+        *,
+        node_subset_from: Optional[Relationship] = None,
+        node_subset_to: Optional[Relationship] = None,
+        pair_subset_between: Optional[Relationship] = None,
+    ):
+        """
+        Create cosine_similarity relationship, optionally constrained by
+        the provided node subsets or pair subset.
+        """
+        _cosine_similarity_rel = self._model.Relationship(
+            f"{{node_u:{self._NodeConceptStr}}} has a cosine similarity to "
+            f"{{node_v:{self._NodeConceptStr}}} of {{score:Float}}"
+        )
+
+        # TODO: Optimization opportunity. In a number of branches below,
+        #   we compute _count_outneighbor_of, which transitively computes
+        #   _outneighbor_of, and then compute _outneighbor_of directly;
+        #   the present code structure makes this a developer-time-efficient
+        #   way to get this off the ground, but of course involves redundant
+        #   work. In future this redundant work could be eliminated.
+
+        # TODO: Optimization opportunity. In some of the cases below
+        #   (unweighted in particular), the node_constraint is redundant with
+        #   the constraints baked into the _count_outneigherbor_of and
+        #   _outneighbor_of relationships. The join with node_constraint
+        #   could be eliminated in those cases. Possibly also relevant to
+        #   other domain-constrained relations.
+
+        # Branch by case to select appropriate count_outneighbor and
+        # outneighbor relationships, and build appropriate constraints
+        # on the domain of the nodes.
+        node_u, node_v = self.Node.ref(), self.Node.ref()
+
+        # Handle the `between` case.
+        if pair_subset_between is not None:
+            # Extract first-position and second-position nodes.
+            first_position_subset = self._model.Relationship(f"{{node:{self._NodeConceptStr}}}")
+            second_position_subset = self._model.Relationship(f"{{node:{self._NodeConceptStr}}}")
+            node_x, node_y = self.Node.ref(), self.Node.ref()
+            where(
+                pair_subset_between(node_x, node_y)
+            ).define(
+                first_position_subset(node_x),
+                second_position_subset(node_y)
+            )
+
+            count_outneighbor_u_rel = self._count_outneighbor_of(first_position_subset)
+            count_outneighbor_v_rel = self._count_outneighbor_of(second_position_subset)
+            outneighbor_u_rel = self._outneighbor_of(first_position_subset)
+            outneighbor_v_rel = self._outneighbor_of(second_position_subset)
+
+            node_constraints = [pair_subset_between(node_u, node_v)]
+
+        # Handle the `from_` case.
+        elif node_subset_from is not None and node_subset_to is None:
+            count_outneighbor_u_rel = self._count_outneighbor_of(node_subset_from)
+            count_outneighbor_v_rel = self._count_outneighbor
+            outneighbor_u_rel = self._outneighbor_of(node_subset_from)
+            outneighbor_v_rel = self._outneighbor
+            # TODO: This case could be optimized via an analog of
+            #   the depth-2 traversal strategy suggested for the equivalent
+            #   case of common_neighbor, but for another day.
+
+            node_constraints = [node_subset_from(node_u)]
+
+        # Handle the `from_`/`to` case.
+        elif node_subset_from is not None and node_subset_to is not None:
+            # Check for object identity optimization.
+            if node_subset_from is node_subset_to:
+                count_outneighbor_u_rel = self._count_outneighbor_of(node_subset_from)
+                count_outneighbor_v_rel = count_outneighbor_u_rel
+                outneighbor_u_rel = self._outneighbor_of(node_subset_from)
+                outneighbor_v_rel = outneighbor_u_rel
+            else:
+                count_outneighbor_u_rel = self._count_outneighbor_of(node_subset_from)
+                count_outneighbor_v_rel = self._count_outneighbor_of(node_subset_to)
+                outneighbor_u_rel = self._outneighbor_of(node_subset_from)
+                outneighbor_v_rel = self._outneighbor_of(node_subset_to)
+
+            node_constraints = [node_subset_from(node_u), node_subset_to(node_v)]
+
+        # Handle the `full` case.
+        else:
+            count_outneighbor_u_rel = self._count_outneighbor
+            count_outneighbor_v_rel = self._count_outneighbor
+            outneighbor_u_rel = self._outneighbor
+            outneighbor_v_rel = self._outneighbor
+
+            node_constraints = []
+
+        # Define cosine similarity logic for both weighted and unweighted cases.
         if not self.weighted:
-            node_u, node_v = self.Node.ref(), self.Node.ref()
-            count_outneighor_u, count_outneighor_v, score = Integer.ref(), Integer.ref(), Float.ref()
+            # Unweighted case: use count of common outneighbors.
+            count_outneighor_u, count_outneighor_v = Integer.ref(), Integer.ref()
+            common_outneighbor_node = self.Node.ref()
+            score = Float.ref()
 
             where(
-                self._count_outneighbor(node_u, count_outneighor_u),
-                self._count_outneighbor(node_v, count_outneighor_v),
-                c_common := self._count_common_outneighbor_fragment(node_u, node_v),
+                *node_constraints,
+                count_outneighbor_u_rel(node_u, count_outneighor_u),
+                count_outneighbor_v_rel(node_v, count_outneighor_v),
+                c_common := count(common_outneighbor_node).per(node_u, node_v).where(
+                    outneighbor_u_rel(node_u, common_outneighbor_node),
+                    outneighbor_v_rel(node_v, common_outneighbor_node),
+                ),
                 score := c_common / sqrt(count_outneighor_u * count_outneighor_v),
             ).define(
                 _cosine_similarity_rel(node_u, node_v, score)
             )
         else:
-            node_u, node_v = self.Node.ref(), self.Node.ref()
+            # Weighted case: use dot product and norms.
             node_uk, node_vk = self.Node.ref(), self.Node.ref()
             wu, wv = Float.ref(), Float.ref()
+
             where(
+                *node_constraints,
                 squared_norm_wu := sum(node_uk, wu * wu).per(node_u).where(self._weight(node_u, node_uk, wu)),
                 squared_norm_wv := sum(node_vk, wv * wv).per(node_v).where(self._weight(node_v, node_vk, wv)),
                 wu_dot_wv := self._wu_dot_wv_fragment(node_u, node_v),
@@ -5608,19 +6317,69 @@ class Graph():
 
 
     @include_in_docs
-    def adamic_adar(self):
-        """Returns a ternary relationship containing the Adamic-Adar index for all pairs of nodes.
+    def adamic_adar(
+            self,
+            *,
+            full: Optional[bool] = None,
+            from_: Optional[Relationship] = None,
+            to: Optional[Relationship] = None,
+            between: Optional[Relationship] = None,
+        ):
+        """Returns a ternary relationship containing the Adamic-Adar index for pairs of nodes.
 
         The Adamic-Adar index is a similarity measure between two nodes based
         on the amount of shared neighbors between them, giving more weight to
         common neighbors that are less connected.
 
+        Parameters
+        ----------
+        full : bool, optional
+            If ``True``, computes the Adamic-Adar index for all pairs of nodes in
+            the graph. This computation can be expensive for large graphs, as
+            dependencies can scale quadratically in the number of edges or cubically
+            in the number of nodes. Mutually exclusive with other parameters.
+            Default is ``None``.
+        from_ : Relationship, optional
+            A unary relationship containing a subset of the graph's nodes. When
+            provided, constrains the domain of the Adamic-Adar computation: only
+            Adamic-Adar indices for node pairs where the first node is in this relationship
+            are computed and returned. Mutually exclusive with ``full`` and ``between``.
+            Default is ``None``.
+        to : Relationship, optional
+            A unary relationship containing a subset of the graph's nodes. Can only
+            be used together with the ``from_`` parameter. When provided with ``from_``,
+            constrains the domain of the Adamic-Adar computation: only Adamic-Adar
+            indices for node pairs where the first node is in ``from_`` and the
+            second node is in ``to`` are computed and returned.
+            Default is ``None``.
+        between : Relationship, optional
+            A binary relationship containing pairs of nodes. When provided,
+            constrains the domain of the Adamic-Adar computation: only Adamic-Adar
+            indices for the specific node pairs in this relationship are computed
+            and returned. Mutually exclusive with other parameters.
+            Default is ``None``.
+
         Returns
         -------
         Relationship
             A ternary relationship where each tuple represents a pair of nodes
             and their Adamic-Adar index.
 
+        Raises
+        ------
+        ValueError
+            If ``full`` is provided with any other parameter.
+            If ``between`` is provided with any other parameter.
+            If ``from_`` is provided with any parameter other than ``to``.
+            If none of ``full``, ``from_``, or ``between`` is provided.
+            If ``full`` is not ``True`` or ``None``.
+        AssertionError
+            If ``from_``, ``to``, or ``between`` is not a ``Relationship``.
+            If ``from_``, ``to``, or ``between`` is not attached to the same model as the graph.
+            If ``from_``, ``to``, or ``between`` does not contain the graph's ``Node`` concept.
+            If ``from_`` or ``to`` is not a unary relationship.
+            If ``between`` is not a binary relationship.
+
         Relationship Schema
         -------------------
         ``adamic_adar(node_u, node_v, score)``
@@ -5644,9 +6403,38 @@ class Graph():
 
             AA(u,v) = Σ (1 / log(degree(w)))
 
+        The ``adamic_adar(full=True)`` method computes and caches the full Adamic-Adar
+        relationship for all pairs of nodes, providing efficient reuse across
+        multiple calls. This can be expensive as dependencies can contain O(|E|²) or
+        O(|V|³) tuples depending on graph density.
+
+        Calling ``adamic_adar()`` without arguments raises a ``ValueError``,
+        to ensure awareness and explicit acknowledgement (``full=True``) of this cost.
+
+        In contrast, ``adamic_adar(from_=subset)`` constrains the computation to
+        tuples with the first position in the passed-in ``subset``. The result is
+        not cached; it is specific to the call site. When a significant fraction of
+        the Adamic-Adar relation is needed across a program, ``adamic_adar(full=True)``
+        is typically more efficient. Use ``adamic_adar(from_=subset)`` only
+        when small subsets of the Adamic-Adar relationship are needed
+        collectively across the program.
+
+        The ``to`` parameter can be used together with ``from_`` to further
+        constrain the computation: ``adamic_adar(from_=subset_a, to=subset_b)``
+        computes Adamic-Adar indices only for node pairs where the first node is in
+        ``subset_a`` and the second node is in ``subset_b``. (Since ``adamic_adar``
+        is symmetric in its first two positions, using ``to`` without ``from_`` would
+        be functionally redundant, and is not allowed.)
+
+        The ``between`` parameter provides another way to constrain the computation.
+        Unlike ``from_`` and ``to``, which allow you to independently constrain the first
+        and second positions in ``adamic_adar`` tuples to sets of nodes, ``between``
+        allows you constrain the first and second positions, jointly, to specific pairs
+        of nodes.
+
         Examples
         --------
-        >>> from relationalai.semantics import Model, define, select, Float
+        >>> from relationalai.semantics import Model, define, select, where, Float
         >>> from relationalai.semantics.reasoners.graph import Graph
         >>>
         >>> # 1. Set up an undirected graph
@@ -5665,10 +6453,10 @@ class Graph():
         ...     Edge.new(src=n4, dst=n3),
         ... )
         >>>
-        >>> # 3. Select the Adamic-Adar index for the pair (2, 4)
+        >>> # 3. Select the Adamic-Adar indices from the full relationship
         >>> u, v = Node.ref("u"), Node.ref("v")
         >>> score = Float.ref("score")
-        >>> adamic_adar = graph.adamic_adar()
+        >>> adamic_adar = graph.adamic_adar(full=True)
         >>> select(
         ...     u.id, v.id, score,
         ... ).where(
@@ -5680,33 +6468,193 @@ class Graph():
            id  id2     score
         0   2    4  0.910239
 
+        >>> # 4. Use 'from_' parameter to constrain the set of nodes for the first position
+        >>> # Define a subset containing only node 1
+        >>> subset = model.Relationship(f"{{node:{Node}}} is in subset")
+        >>> node = Node.ref()
+        >>> where(node.id == 1).define(subset(node))
+        >>>
+        >>> # Get Adamic-Adar indices only for pairs where first node is in subset
+        >>> constrained_adamic_adar = graph.adamic_adar(from_=subset)
+        >>> select(u.id, v.id, score).where(constrained_adamic_adar(u, v, score)).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2     score
+        0   1    1  2.885390
+        1   1    4  2.885390
+
+        >>> # 5. Use both 'from_' and 'to' parameters to constrain both positions
+        >>> subset_a = model.Relationship(f"{{node:{Node}}} is in subset_a")
+        >>> subset_b = model.Relationship(f"{{node:{Node}}} is in subset_b")
+        >>> where(node.id == 1).define(subset_a(node))
+        >>> where(node.id == 4).define(subset_b(node))
+        >>>
+        >>> # Get Adamic-Adar indices only where first node is in subset_a and second node is in subset_b
+        >>> constrained_adamic_adar = graph.adamic_adar(from_=subset_a, to=subset_b)
+        >>> select(u.id, v.id, score).where(constrained_adamic_adar(u, v, score)).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2     score
+        0   1    4  2.885390
+
+        >>> # 6. Use 'between' parameter to constrain to specific pairs of nodes
+        >>> pairs = model.Relationship(f"{{node_a:{Node}}} and {{node_b:{Node}}} are a pair")
+        >>> node_a, node_b = Node.ref(), Node.ref()
+        >>> where(node_a.id == 1, node_b.id == 4).define(pairs(node_a, node_b))
+        >>> where(node_a.id == 2, node_b.id == 3).define(pairs(node_a, node_b))
+        >>>
+        >>> # Get Adamic-Adar indices only for the specific pairs (1, 4) and (2, 3)
+        >>> constrained_adamic_adar = graph.adamic_adar(between=pairs)
+        >>> select(u.id, v.id, score).where(constrained_adamic_adar(u, v, score)).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2     score
+        0   1    4  2.885390
+        1   2    3  1.442695
+
         """
-        warnings.warn(
-            (
-                "`adamic_adar` presently always computes the similarity "
-                "of all pairs of nodes of the graph. To provide better control over "
-                "the computed subset, `adamic_adar`'s interface will soon "
-                "need to change."
-            ),
-            FutureWarning,
-            stacklevel=2
+        # Validate domain constraint parameters.
+        self._validate_domain_constraint_parameters(
+            'adamic_adar', full, from_, to, between
         )
 
+        # At this point, exactly one of `full`, `from_`, or `between`
+        # has been provided, and if `to` is provided, `from_` is also provided.
+
+        # Handle `between`.
+        if between is not None:
+            self._validate_pair_subset_parameter(between)
+            return self._adamic_adar_between(between)
+
+        # Handle `from_` (and potentially `to`).
+        if from_ is not None:
+            self._validate_node_subset_parameter('from_', from_)
+            if to is not None:
+                self._validate_node_subset_parameter('to', to)
+                return self._adamic_adar_from_to(from_, to)
+            return self._adamic_adar_from(from_)
+
+        # Handle `full`.
         return self._adamic_adar
 
     @cached_property
     def _adamic_adar(self):
-        """Lazily define and cache the self._adamic_adar relationship."""
-        _adamic_adar_rel = self._model.Relationship(f"{{node_u:{self._NodeConceptStr}}} and {{node_v:{self._NodeConceptStr}}} have adamic adar score {{score:Float}}")
+        """Lazily define and cache the full adamic_adar relationship."""
+        _adamic_adar_rel = self._create_adamic_adar_relationship()
         _adamic_adar_rel.annotate(annotations.track("graphs", "adamic_adar"))
+        return _adamic_adar_rel
+
+    def _adamic_adar_from(self, node_subset_from: Relationship):
+        """
+        Create an adamic_adar relationship, with the first position in each
+        tuple constrained to be in the given subset of nodes. Note this relationship
+        is not cached; it is specific to the callsite.
+        """
+        _adamic_adar_rel = self._create_adamic_adar_relationship(
+            node_subset_from=node_subset_from
+        )
+        _adamic_adar_rel.annotate(annotations.track("graphs", "adamic_adar_from"))
+        return _adamic_adar_rel
+
+    def _adamic_adar_from_to(self, node_subset_from: Relationship, node_subset_to: Relationship):
+        """
+        Create an adamic_adar relationship, with the first position in each
+        tuple constrained to be in `node_subset_from`, and the second position in
+        each tuple constrained to be in `node_subset_to`. Note this relationship
+        is not cached; it is specific to the callsite.
+        """
+        _adamic_adar_rel = self._create_adamic_adar_relationship(
+            node_subset_from=node_subset_from,
+            node_subset_to=node_subset_to
+        )
+        _adamic_adar_rel.annotate(annotations.track("graphs", "adamic_adar_from_to"))
+        return _adamic_adar_rel
+
+    def _adamic_adar_between(self, pair_subset_between: Relationship):
+        """
+        Create an adamic_adar relationship, with the first and second position
+        in each tuple jointly constrained to be in the given set of pairs
+        of nodes. Note this relationship is not cached;
+        it is specific to the callsite.
+        """
+        _adamic_adar_rel = self._create_adamic_adar_relationship(
+            pair_subset_between=pair_subset_between
+        )
+        _adamic_adar_rel.annotate(annotations.track("graphs", "adamic_adar_between"))
+        return _adamic_adar_rel
 
+    def _create_adamic_adar_relationship(
+        self,
+        *,
+        node_subset_from: Optional[Relationship] = None,
+        node_subset_to: Optional[Relationship] = None,
+        pair_subset_between: Optional[Relationship] = None,
+    ):
+        """
+        Create adamic_adar relationship, optionally constrained by the provided
+        node subsets or pair subset.
+        """
+        _adamic_adar_rel = self._model.Relationship(
+            f"{{node_u:{self._NodeConceptStr}}} and {{node_v:{self._NodeConceptStr}}} "
+            f"have adamic adar score {{score:Float}}"
+        )
+
+        # NOTE: Handling of the common_neighbor relation (`common_neighbor_rel`)
+        #   differs in each case, whereas handling of the count_neighbor relation
+        #   (`count_neighbor_rel`) is: a) the same among the constrained cases;
+        #   and b) different in the unconstrained case. As such we handle
+        #   `common_neighbor_rel` in the branches by case below, and handle
+        #   `count_neighbor_rel` in a separate constrained/unconstrained branch later.
+
+        # Handle the `between` case.
+        if pair_subset_between is not None:
+            # Get the appropriate common_neighbor relationship.
+            common_neighbor_rel = self._common_neighbor_between(pair_subset_between)
+
+        # Handle the `from_` case.
+        elif node_subset_from is not None and node_subset_to is None:
+            # Get the appropriate common_neighbor relationship.
+            common_neighbor_rel = self._common_neighbor_from(node_subset_from)
+
+        # Handle the `from_`/`to` case.
+        elif node_subset_from is not None and node_subset_to is not None:
+            common_neighbor_rel = self._common_neighbor_from_to(node_subset_from, node_subset_to)
+            # Note that _common_neighbor_from_to handles optimization
+            # when the from_ and to sets are object-identical.
+
+        # Handle the `full` case.
+        else:
+            # Use cached full relationship.
+            common_neighbor_rel = self._common_neighbor
+
+        # Handle `count_neighbor_rel` for unconstrained versus constrained cases.
+        if pair_subset_between is None and node_subset_from is None:
+             # Unconstrained case.
+            count_neighbor_rel = self._count_neighbor
+
+        else:
+            # Constrained cases.
+
+            # Extract common neighbors that appear in
+            # the constrained common_neighbor relationship.
+            common_neighbors_subset = self._model.Relationship(
+                f"{{node:{self._NodeConceptStr}}} is a relevant common neighbor"
+            )
+            node_x, node_y, neighbor_z = self.Node.ref(), self.Node.ref(), self.Node.ref()
+            where(
+                common_neighbor_rel(node_x, node_y, neighbor_z)
+            ).define(
+                common_neighbors_subset(neighbor_z)
+            )
+
+            # From those common neighbors,
+            # build a constrained count_neighbor relationship.
+            count_neighbor_rel = self._count_neighbor_of(common_neighbors_subset)
+
+        # Define the Adamic-Adar aggregation using the selected relationships.
         node_u, node_v, common_neighbor = self.Node.ref(), self.Node.ref(), self.Node.ref()
         neighbor_count = Integer.ref()
-
         where(
             _score := sum(common_neighbor, 1.0 / natural_log(neighbor_count)).per(node_u, node_v).where(
-                self._common_neighbor(node_u, node_v, common_neighbor),
-                self._count_neighbor(common_neighbor, neighbor_count),
+                common_neighbor_rel(node_u, node_v, common_neighbor),
+                count_neighbor_rel(common_neighbor, neighbor_count),
             )
         ).define(_adamic_adar_rel(node_u, node_v, _score))