From d161bcf1a285473972fb7111d1684bd8c7e887cc Mon Sep 17 00:00:00 2001 From: Dimitri Yatsenko Date: Thu, 30 Apr 2026 12:07:58 -0500 Subject: [PATCH] docs: document Top(order_by="_name") in the hidden-attribute matrix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Top.order_by is not validated against heading.names — it flows from condition.py:142-148 (type check only) through expression.py:241-254 (restrict() short-circuits on Top before the heading.names check) into _flatten_attribute_list / _wrap_attributes, which quote the name and concatenate it into ORDER BY. So a hidden column shapes the result order even though its value never returns to Python. This is the same shape as string restrictions: DataJoint-generated SQL references the hidden column, but the visible-only filter on the SELECT list keeps its value out of the result set. Worth one row in the behavior matrix so users querying "5 most recently populated rows" via Top(5, order_by="_job_start_time DESC") see it as an explicitly supported pattern rather than an undocumented bypass. --- src/reference/specs/table-declaration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/reference/specs/table-declaration.md b/src/reference/specs/table-declaration.md index 9bd720ad..2feb2c96 100644 --- a/src/reference/specs/table-declaration.md +++ b/src/reference/specs/table-declaration.md @@ -191,6 +191,7 @@ These columns are populated by DataJoint internals via raw SQL during the `popul | Natural-join namesake matching | Excluded | | Dict restriction `Table & {"_name": value}` | Silently ignored | | String restriction `Table & "_name = ..."` | Included (passes to SQL) | +| `Top(order_by="_name")` | Allowed (passes through to SQL `ORDER BY`; no heading validation) | | `insert()`, `insert1()` | Rejected — ``KeyError("`_name` is not in the table heading")`` | | `update1()` | Rejected — ``DataJointError("Attribute `_name` not found.")`` | | `insert(..., ignore_extra_fields=True)` | Silently dropped (key not written) |