[BSE-4155] Add support for the Project relational node

pydough/relational/__init__.py

@@ -3,10 +3,8 @@
 """
 
 __all__ = [
-    "Column",
     "Relational",
 ]
 from .abstract import (
-    Column,
     Relational,
 )

pydough/relational/abstract.py

@@ -1,17 +1,17 @@
 """
-This module contains the abstract base classes for the relational
+This file contains the abstract base classes for the relational
 representation. This roughly maps to a Relational Algebra representation
 but is not exact because it needs to maintain PyDough traits that define
 ordering and other properties of the relational expression.
 """
 
 from abc import ABC, abstractmethod
 from collections.abc import MutableMapping, MutableSequence
-from typing import Any, NamedTuple
+from typing import Any
 
-from sqlglot.expressions import Expression
+from sqlglot.expressions import Expression as SQLGlotExpression
 
-from pydough.pydough_ast.expressions import PyDoughExpressionAST
+from .relational_expressions.abstract import RelationalExpression
 
 
 class Relational(ABC):
@@ -32,55 +32,48 @@ def inputs(self) -> MutableSequence["Relational"]:
         """
 
     @property
-    def traits(self) -> MutableMapping[str, Any]:
+    @abstractmethod
+    def columns(self) -> MutableMapping[str, RelationalExpression]:
         """
-        Return the traits of the relational expression.
-        The traits in general may have a variable schema,
-        but each entry should be strongly defined. Here are
-        traits that should always be available:
+        Returns the columns of the relational expression.
 
-        - orderings: MutableSequence[PyDoughExpressionAST]
+        TODO: Associate an ordering in the future to avoid unnecessary SQL with the
+        final ordering of the root nodes.
 
         Returns:
-            MutableMapping[str, Any]: The traits of the relational expression.
+            MutableMapping[str, RelationalExpression]: The columns of the relational expression.
+                This does not have a defined ordering.
         """
-        return {"orderings": self.orderings}
 
-    @property
     @abstractmethod
-    def orderings(self) -> MutableSequence["PyDoughExpressionAST"]:
-        """
-        Returns the PyDoughExpressionAST that the relational expression is ordered by.
-        Each PyDoughExpressionAST is a result computed relative to the given set of columns.
-
-        Returns:
-            MutableSequence[PyDoughExpressionAST]: The PyDoughExpressionAST that the relational expression is ordered by,
-            possibly empty.
+    def equals(self, other: "Relational") -> bool:
         """
+        Determine if two relational nodes are exactly identical,
+        including column ordering.
 
-    @property
-    @abstractmethod
-    def columns(self) -> MutableSequence["Column"]:
-        """
-        Returns the columns of the relational expression.
+        Args:
+            other (Relational): The other relational node to compare against.
 
         Returns:
-            MutableSequence[Column]: The columns of the relational expression.
+            bool: Are the two relational nodes equal.
         """
 
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, Relational) and self.equals(other)
+
     @abstractmethod
-    def to_sqlglot(self) -> "Expression":
-        """Translate the given relational expression
+    def to_sqlglot(self) -> SQLGlotExpression:
+        """Translate the given relational node
         and its children to a SQLGlot expression.
 
         Returns:
-            Expression: A SqlGlot expression representing the relational expression.
+            Expression: A SqlGlot expression representing the relational node.
         """
 
     @abstractmethod
     def to_string(self) -> str:
         """
-        Convert the relational expression to a string.
+        Convert the relational node to a string.
 
         TODO: Refactor this API to include some form of string
         builder so we can draw lines between children properly.
@@ -90,38 +83,5 @@ def to_string(self) -> str:
             with this node at the root.
         """
 
-    @abstractmethod
-    def can_merge(self, other: "Relational") -> bool:
-        """
-        Determine if two relational nodes can be merged together.
-
-        Args:
-            other (Relational): The other relational node to merge with.
-
-        Returns:
-            bool: Can the two relational nodes be merged together.
-        """
-
-    @abstractmethod
-    def merge(self, other: "Relational") -> "Relational":
-        """
-        Merge two relational nodes together to produce one output
-        relational node. This requires can_merge to return True.
-
-        Args:
-            other (Relational): The other relational node to merge with.
-
-        Returns:
-            Relational: A new relational node that is the result of merging
-            the two input relational nodes together and removing any redundant
-            components.
-        """
-
-
-class Column(NamedTuple):
-    """
-    An column expression consisting of a name and an expression.
-    """
-
-    name: str
-    expr: "PyDoughExpressionAST"
+    def __repr__(self) -> str:
+        return self.to_string()

pydough/relational/project.py

@@ -0,0 +1,52 @@
+"""
+This file contains the relational implementation for a "project". This is our
+relational representation for a "calc" that involves any compute steps and can include
+adding or removing columns (as well as technically reordering). In general, we seek to
+avoid introducing extra nodes just to reorder or prune columns, so ideally their use
+should be sparse.
+"""
+
+from collections.abc import MutableMapping
+
+from sqlglot.expressions import Expression
+
+from .abstract import Relational
+from .relational_expressions import RelationalExpression
+from .single_relational import SingleRelational
+
+
+class Project(SingleRelational):
+    """
+    The Project node in the relational tree. This node represents a "calc" in
+    relational algebra, which should involve some "compute" functions and may
+    involve adding, removing, or reordering columns.
+    """
+
+    def __init__(
+        self,
+        input: Relational,
+        columns: MutableMapping[str, RelationalExpression],
+    ) -> None:
+        super().__init__(input)
+        self._columns: MutableMapping[str, RelationalExpression] = columns
+
+    @property
+    def columns(self) -> MutableMapping[str, RelationalExpression]:
+        return self._columns
+
+    def to_sqlglot(self) -> Expression:
+        raise NotImplementedError(
+            "Conversion to SQLGlot Expressions is not yet implemented."
+        )
+
+    def equals(self, other: Relational) -> bool:
+        return (
+            isinstance(other, Project)
+            # TODO: Do we need a fast path for caching the inputs?
+            and self.input == other.input
+            and self.columns == other.columns
+        )
+
+    def to_string(self) -> str:
+        # TODO: Should we visit the input?
+        return f"PROJECT(columns={self.columns})"

pydough/relational/relational_expressions/__init__.py

@@ -0,0 +1,10 @@
+"""
+TODO: add module-level docstring
+"""
+
+__all__ = [
+    "RelationalExpression",
+]
+from .abstract import (
+    RelationalExpression,
+)

pydough/relational/relational_expressions/abstract.py

@@ -0,0 +1,66 @@
+"""
+This file contains the abstract base classes for the relational
+expression representation. Relational expressions are representations
+of literals, column accesses, or other functions that are used in the
+relational tree to build the final SQL query.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from sqlglot.expressions import Expression as SQLGlotExpression
+
+__all__ = ["RelationalExpression"]
+
+from pydough.types import PyDoughType
+
+
+class RelationalExpression(ABC):
+    def __init__(self, data_type: PyDoughType) -> None:
+        self._data_type: PyDoughType = data_type
+
+    @property
+    def data_type(self) -> PyDoughType:
+        return self._data_type
+
+    @property
+    def is_aggregation(self) -> bool:
+        return False
+
+    @abstractmethod
+    def equals(self, other: "RelationalExpression") -> bool:
+        """
+        Determine if two RelationalExpression nodes are exactly identical,
+        including ordering. This does not check if two expression are equal
+        after any alterations, for example commuting the inputs.
+
+        Args:
+            other (RelationalExpression): The other relational expression to compare against.
+
+        Returns:
+            bool: Are the two relational expressions equal.
+        """
+
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, RelationalExpression) and self.equals(other)
+
+    @abstractmethod
+    def to_string(self) -> str:
+        """
+        Convert the relational expression to a string.
+
+        Returns:
+            str: A string representation of the this expression including converting
+            any of its inputs to strings.
+        """
+
+    def __repr__(self) -> str:
+        return self.to_string()
+
+    @abstractmethod
+    def to_sqlglot(self) -> SQLGlotExpression:
+        """Translate the given relational expression
+
+        Returns:
+            Expression: A SqlGlot expression representing the relational expression.
+        """

pydough/relational/relational_expressions/column_reference.py

@@ -0,0 +1,49 @@
+"""
+The representation of a column access for use in a relational tree.
+The provided name of the column should match the name that can be used
+for the column in the input node.
+"""
+
+__all__ = ["ColumnReference"]
+
+from sqlglot.expressions import Expression as SQLGlotExpression
+
+from pydough.types import PyDoughType
+
+from .abstract import RelationalExpression
+
+
+class ColumnReference(RelationalExpression):
+    """
+    The Expression implementation for accessing a column
+    in a relational node.
+    """
+
+    def __init__(self, name: str, data_type: PyDoughType):
+        super().__init__(data_type)
+        self._name: str = name
+
+    def __hash__(self) -> int:
+        return hash((self.name, self.data_type))
+
+    @property
+    def name(self) -> object:
+        """
+        The name of the column.
+        """
+        return self._name
+
+    def to_sqlglot(self) -> SQLGlotExpression:
+        raise NotImplementedError(
+            "Conversion to SQLGlot Expressions is not yet implemented."
+        )
+
+    def to_string(self) -> str:
+        return f"Column(name={self.name}, type={self.data_type})"
+
+    def equals(self, other: object) -> bool:
+        return (
+            isinstance(other, ColumnReference)
+            and (self.data_type == other.data_type)
+            and (self.name == other.name)
+        )

pydough/relational/relational_expressions/literal_expression.py

@@ -0,0 +1,56 @@
+"""
+The representation of a literal value for using in a relational
+expression.
+"""
+
+__all__ = ["LiteralExpression"]
+
+from typing import Any
+
+from sqlglot.expressions import Expression as SQLGlotExpression
+
+from pydough.types import PyDoughType
+
+from .abstract import RelationalExpression
+
+
+class LiteralExpression(RelationalExpression):
+    """
+    The Expression implementation for an Literal value
+    in a relational node. There are no restrictions on the
+    relationship between the value and the type so we can
+    represent arbitrary Python classes as any type and lowering
+    to SQL is responsible for determining how this can be
+    achieved (e.g. casting) or translation must prevent this
+    from being generated.
+    """
+
+    def __init__(self, value: Any, data_type: PyDoughType):
+        super().__init__(data_type)
+        self._value: Any = value
+
+    def __hash__(self) -> int:
+        # Note: This will break if the value isn't hashable.
+        return hash((self.value, self.data_type))
+
+    @property
+    def value(self) -> object:
+        """
+        The literal's Python value.
+        """
+        return self._value
+
+    def to_sqlglot(self) -> SQLGlotExpression:
+        raise NotImplementedError(
+            "Conversion to SQLGlot Expressions is not yet implemented."
+        )
+
+    def to_string(self) -> str:
+        return f"Literal(value={self.value}, type={self.data_type})"
+
+    def equals(self, other: object) -> bool:
+        return (
+            isinstance(other, LiteralExpression)
+            and (self.data_type == other.data_type)
+            and (self.value == other.value)
+        )