Bug: Unhandled exceptions and descriptive errors for unsupported partition keys (literals, non-iterables, relationship references)

[juankx-bodo]

Passing a single integer or non-iterable value to .PARTITION(by=...) (e.g., by=1) causes PyDough to crash with an unhandled Python TypeError: 'int' object is not iterable inside PARTITION() when attempting list(by).

PyDough should either handle single scalar terms gracefully or raise a descriptive validation error explaining allowed partition keys.

Minimal Reproducible Example

result = customers.WHERE(
    account_balance > 0
).PARTITION(
    name="all_group",
    by=1
).CALCULATE(
    total=COUNT(customers)
)

Error Traceback

Traceback (most recent call last):
  File "/home/juankx/svc/PyDough/pydough_test.py", line 166, in <module>
    unqualified_node : UnqualifiedNode = pydough.from_string(pydough_code, answer_variable, tester.session.metadata)
  File "/home/juankx/svc/PyDough/pydough/unqualified/unqualified_transform.py", line 524, in from_string
    exec(compile_ast, execution_context, execution_context)
  File "<ast>", line 3, in <module>
  File "/home/juankx/svc/PyDough/pydough/unqualified/unqualified_node.py", line 379, in PARTITION
    return UnqualifiedPartition(self, name, list(by))
TypeError: 'int' object is not iterable

Expected Behavior

• If by=1 is an invalid partition key: PyDough should raise a descriptive domain error (e.g., Invalid partition key '1'. Partition keys must be references to scalar expressions from the data collection) instead of failing on a raw list(by) call.
• If single non-iterable terms are allowed: PARTITION() should handle it.

Documentation Context

According to the PyDough Partition Documentation:

Warning: PyDough currently only supports using references to scalar expressions from the data collection itself as partition keys, not an ancestor term, or a term from a child collection, or the result of a function call.

[juankx-bodo]

Follow-Up: Unsupported Relationship References in PARTITION(by=...)

Another instance of poor error handling in PARTITION(by=...) occurs when passing a relationship/child reference (e.g., customer.key) as a partition key.

Code Example

result = orders.PARTITION(
    name="customer_ship_groups",
    by=(customer.key, ship_priority)
).CALCULATE(
    customer_id=customer.key,
    ship_priority=ship_priority,
    total_order_amount=SUM(total_price)
)

Error Output

Traceback (most recent call last):
  File "/home/juankx/svc/PyDough/pydough_test.py", line 179, in <module>
    sql = pydough.to_sql(unqualified_node, session=tester.session)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/juankx/svc/PyDough/pydough/evaluation/evaluate_unqualified.py", line 163, in to_sql
    qualified: PyDoughQDAG = qualify_node(node, session)
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/juankx/svc/PyDough/pydough/unqualified/qualification.py", line 1403, in qualify_node
    return qual.qualify_node(
           ^^^^^^^^^^^^^^^^^^
  File "/home/juankx/svc/PyDough/pydough/unqualified/qualification.py", line 1347, in qualify_node
    answer = self.qualify_calculate(unqualified, context, is_child)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/juankx/svc/PyDough/pydough/unqualified/qualification.py", line 687, in qualify_calculate
    qualified_term = self.qualify_expression(term, qualified_parent, children)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/juankx/svc/PyDough/pydough/unqualified/qualification.py", line 1121, in qualify_expression
    answer: PyDoughQDAG = self.qualify_node(unqualified, context, children, True)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/juankx/svc/PyDough/pydough/unqualified/qualification.py", line 1344, in qualify_node
    answer = self.qualify_access(unqualified, context, children, is_child)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/juankx/svc/PyDough/pydough/unqualified/qualification.py", line 593, in qualify_access
    qualified_parent: PyDoughCollectionQDAG = self.qualify_collection(
                                              ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/juankx/svc/PyDough/pydough/unqualified/qualification.py", line 1092, in qualify_collection
    answer: PyDoughQDAG = self.qualify_node(unqualified, context, [], is_child)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/juankx/svc/PyDough/pydough/unqualified/qualification.py", line 1344, in qualify_node
    answer = self.qualify_access(unqualified, context, children, is_child)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/juankx/svc/PyDough/pydough/unqualified/qualification.py", line 613, in qualify_access
    term = qualified_parent.get_term(name)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/juankx/svc/PyDough/pydough/qdag/collections/partition_by.py", line 153, in get_term
    self.verify_term_exists(term_name)
  File "/home/juankx/svc/PyDough/pydough/qdag/collections/collection_qdag.py", line 428, in verify_term_exists
    raise pydough.active_session.error_builder.term_not_found(
pydough.errors.error_types.PyDoughQDAGException: Unrecognized term of TPCH.Partition(orders, name='customer_ship_groups', by=('key', 'ship_priority')): 'customer'. Did you mean: key, orders, ship_priority?

Key Inconsistencies & Issues

1. Term Misparsing: The error message reports by=('key', 'ship_priority'). It incorrectly strips customer. from customer.key and maps it to orders.key (key), which changes the semantic meaning of the expression.

2. Missing Input Validation: According to the PyDough Partition Documentation, partition keys currently only support direct scalar expressions from the data collection itself (not child/ancestor/relationship terms).

3. Cryptic Error: Rather than catching unsupported partition key types (customer.key) upfront and displaying a clear limitation message (e.g., "Partition keys must be direct scalar expressions from the root collection, not relationship paths"), PyDough silently misinterprets the key and throws a downstream Unrecognized term: 'customer' error during .CALCULATE().

Expected Behavior

PyDough should validate the terms passed to by= upfront and raise an informative error explaining DSL restrictions when invalid partition keys are provided.

Correct Alternative Usage

To achieve this calculation, users must explicitly use direct scalar fields from the collection (customer_key instead of customer.key):

result = orders.PARTITION(
    name="customer_ship_groups", 
    by=(customer_key, ship_priority)
).CALCULATE(
    customer_key,
    ship_priority,
    order_total=SUM(total_price),
)

Schema Context (TPCH Collections Used)

orders
├── customer_key
├── key
├── ship_priority
├── total_price
└── customer [one member of customers]

customers
├── key
└── orders [multiple orders]