feat(query-compiler): support orderBy on to-many relation scalar fields

Implement ordering by scalar fields of to-many (1:m and m:n) relations
using correlated subqueries. The correlated subquery selects the field
value from the first matching related record (LIMIT 1), naturally
producing NULL when no related records exist.

Given the following schema:

  model Item {
    id           Int      @id
    localization ItemI18n[]
  }
  model ItemI18n {
    id     Int    @id
    name   String
    itemId Int
    item   Item   @relation(fields: [itemId], references: [id])
  }

This PR enables:

  prisma.item.findMany({ orderBy: { localization: { name: 'asc' } } })
  prisma.item.findMany({ orderBy: { localization: { name: { sort: 'asc', nulls: 'first' } } } })

which was previously limited to aggregate-only ordering (`_count`).

Changes:
- order_by.rs: add `OrderByToManyField` variant and `OrderBy::to_many_field` constructor
- order_by_objects.rs: expose scalar fields in `*OrderByRelationAggregateInput` DMMF type
- query_arguments.rs: parse new scalar field name inside a to-many relation orderBy
- ordering.rs: generate correlated sub-SELECT for 1:m and m:n relations
- cursor_condition.rs: handle `ToManyField` in cursor-based pagination
- select/mod.rs: skip join building for `ToManyField` (subquery is self-contained)
- record.rs: extract field value for `ToManyField` in sort record comparison

Fixes prisma/prisma#5837

Author: DevFigueiredo

query-compiler/core/src/query_graph_builder/extractors/query_arguments.rs

@@ -119,15 +119,34 @@ fn process_order_object(
             match field {
                 Field::Relation(rf) if rf.is_list() => {
                     let object: ParsedInputMap<'_> = field_value.try_into()?;
+                    debug_assert!(object.len() <= 1, "to-many relation orderBy object must have at most one field");
 
-                    path.push(rf.into());
+                    path.push(rf.clone().into());
 
                     let (inner_field_name, inner_field_value) = object.into_iter().next().unwrap();
-                    let sort_aggregation = extract_sort_aggregation(inner_field_name.as_ref())
-                        .expect("To-many relation orderBy must be an aggregation ordering.");
 
-                    let (sort_order, _) = extract_order_by_args(inner_field_value)?;
-                    Ok(Some(OrderBy::to_many_aggregation(path, sort_order, sort_aggregation)))
+                    if let Some(sort_aggregation) = extract_sort_aggregation(inner_field_name.as_ref()) {
+                        let (sort_order, _) = extract_order_by_args(inner_field_value)?;
+                        Ok(Some(OrderBy::to_many_aggregation(path, sort_order, sort_aggregation)))
+                    } else {
+                        // The field name refers to a scalar field on the related model; order by
+                        // its value via a correlated subquery (LIMIT 1).
+                        let related_model: ParentContainer = rf.related_model().into();
+                        let related_field = related_model
+                            .find_field(&inner_field_name)
+                            .expect("Fields must be valid after validation passed.");
+
+                        match related_field {
+                            Field::Scalar(sf) => {
+                                let (sort_order, nulls_order) = extract_order_by_args(inner_field_value)?;
+                                Ok(Some(OrderBy::to_many_field(sf, path, sort_order, nulls_order)))
+                            }
+                            _ => Err(QueryGraphBuilderError::InputError(format!(
+                                "Field '{}' on '{}' used in a to-many relation orderBy must be a scalar field or an aggregation function.",
+                                inner_field_name, rf.name()
+                            ))),
+                        }
+                    }
                 }
 
                 Field::Relation(rf) => {

query-compiler/query-builders/sql-query-builder/src/cursor_condition.rs

@@ -442,6 +442,7 @@ fn order_definitions(
             OrderBy::ScalarAggregation(order_by) => cursor_order_def_aggregation_scalar(order_by, order_by_def),
             OrderBy::ToManyAggregation(order_by) => cursor_order_def_aggregation_rel(order_by, order_by_def),
             OrderBy::Relevance(order_by) => cursor_order_def_relevance(order_by, order_by_def),
+            OrderBy::ToManyField(order_by) => cursor_order_def_to_many_field(order_by, order_by_def),
         })
         .collect_vec()
 }
@@ -515,6 +516,26 @@ fn cursor_order_def_relevance(order_by: &OrderByRelevance, order_by_def: &OrderB
     }
 }
 
+/// Build a CursorOrderDefinition for ordering by a scalar field on a to-many relation.
+/// The subquery expression may return NULL when no related records exist, so cursors treat
+/// this as a nullable ordering.
+fn cursor_order_def_to_many_field(
+    order_by: &OrderByToManyField,
+    order_by_def: &OrderByDefinition,
+) -> CursorOrderDefinition {
+    // The OrderByDefinition.joins for ToManyField only covers intermediary hops, not the
+    // final to-many hop itself, so calling foreign_keys_from_order_path would produce
+    // length mismatches and cause panics or incorrect alias references. The correlated
+    // subquery built in ordering.rs handles nullability, so we simply mark this as
+    // nullable with no extra FK predicates.
+    CursorOrderDefinition {
+        sort_order: order_by.sort_order,
+        order_column: order_by_def.order_column.clone(),
+        order_fks: None,
+        on_nullable_fields: true,
+    }
+}
+
 fn foreign_keys_from_order_path(path: &[OrderByHop], joins: &[AliasedJoin]) -> Option<Vec<CursorOrderForeignKey>> {
     let (before_last_hop, last_hop) = take_last_two_elem(path);
 

query-compiler/query-builders/sql-query-builder/src/ordering.rs

@@ -50,6 +50,7 @@ impl OrderByBuilder {
                     self.build_order_aggr_scalar(order_by, needs_reversed_order, ctx)
                 }
                 OrderBy::ToManyAggregation(order_by) => self.build_order_aggr_rel(order_by, needs_reversed_order, ctx),
+                OrderBy::ToManyField(order_by) => self.build_order_to_many_field(order_by, needs_reversed_order, ctx),
                 OrderBy::Relevance(order_by) => {
                     reachable_only_with_capability!(ConnectorCapability::NativeFullTextSearch);
                     self.build_order_relevance(order_by, needs_reversed_order, ctx)
@@ -145,6 +146,177 @@ impl OrderByBuilder {
         }
     }
 
+    /// Orders by a specific scalar field on a to-many related model using a correlated subquery.
+    ///
+    /// Generated SQL:
+    /// ```sql
+    /// ORDER BY (
+    ///   SELECT <related_table>.<field> FROM <related_table>
+    ///   WHERE <related_table>.<fk> = <parent_table>.<pk>
+    ///   ORDER BY <related_table>.<field> {direction}
+    ///   LIMIT 1
+    /// ) {direction}
+    /// ```
+    fn build_order_to_many_field(
+        &mut self,
+        order_by: &OrderByToManyField,
+        needs_reversed_order: bool,
+        ctx: &Context<'_>,
+    ) -> OrderByDefinition {
+        let order: Option<Order> = Some(into_order(
+            &order_by.sort_order,
+            order_by.nulls_order.as_ref(),
+            needs_reversed_order,
+        ));
+
+        // The inner subquery uses the original (non-reversed) direction so that LIMIT 1
+        // consistently picks the representative value regardless of the outer pagination
+        // direction. Only the outer ORDER BY clause needs to respect needs_reversed_order.
+        let (intermediary_joins, subquery) =
+            self.compute_subquery_for_to_many_field(order_by, ctx);
+
+        let order_definition: OrderDefinition = (subquery.clone(), order);
+
+        OrderByDefinition {
+            order_column: subquery,
+            order_definition,
+            joins: intermediary_joins,
+        }
+    }
+
+    /// Builds the correlated subquery expression and any intermediary joins for a to-many field ordering.
+    fn compute_subquery_for_to_many_field(
+        &mut self,
+        order_by: &OrderByToManyField,
+        ctx: &Context<'_>,
+    ) -> (Vec<AliasedJoin>, Expression<'static>) {
+        let intermediary_hops = order_by.intermediary_hops();
+        let to_many_hop = order_by.to_many_hop().as_relation_hop().unwrap();
+
+        // Build joins for all hops leading up to the to-many relation.
+        let parent_alias = self.parent_alias.clone();
+        let intermediary_joins = self.compute_one2m_join(intermediary_hops, parent_alias.as_ref(), ctx);
+
+        // The alias for the context table that the correlated subquery references.
+        let context_alias = intermediary_joins.last().map(|j| j.alias.clone()).or(parent_alias);
+
+        let subquery = if to_many_hop.relation().is_many_to_many() {
+            self.build_m2m_correlated_subquery(to_many_hop, &order_by.field, &order_by.sort_order, order_by.nulls_order.as_ref(), context_alias, ctx)
+        } else {
+            self.build_one2m_correlated_subquery(to_many_hop, &order_by.field, &order_by.sort_order, order_by.nulls_order.as_ref(), context_alias, ctx)
+        };
+
+        (intermediary_joins, subquery)
+    }
+
+    /// Builds a correlated sub-SELECT for one-to-many relations:
+    /// `(SELECT field FROM Related WHERE Related.fk = Parent.pk ORDER BY field {dir} LIMIT 1)`
+    fn build_one2m_correlated_subquery(
+        &mut self,
+        rf: &RelationFieldRef,
+        field: &ScalarFieldRef,
+        sort_order: &SortOrder,
+        nulls_order: Option<&NullsOrder>,
+        context_alias: Option<String>,
+        ctx: &Context<'_>,
+    ) -> Expression<'static> {
+        let (left_fields, right_fields) = if rf.is_inlined_on_enclosing_model() {
+            // FK is on the parent model side.
+            (rf.scalar_fields(), rf.referenced_fields())
+        } else {
+            // FK is on the related model side.
+            (
+                rf.related_field().referenced_fields(),
+                rf.related_field().scalar_fields(),
+            )
+        };
+
+        // WHERE right_field (on related table) = left_field (on parent, with alias if applicable)
+        let conditions: Vec<Expression<'static>> = left_fields
+            .iter()
+            .zip(right_fields.iter())
+            .map(|(left, right)| {
+                let parent_col = left.as_column(ctx).opt_table(context_alias.clone());
+                let related_col = right.as_column(ctx);
+                parent_col.equals(related_col).into()
+            })
+            .collect();
+
+        let field_col = field.as_column(ctx);
+        // Use the original (non-reversed) direction so LIMIT 1 always picks the
+        // stable representative value for this sort key.
+        let inner_order = into_order(sort_order, nulls_order, false);
+        let inner_order_def: OrderDefinition<'static> = (field_col.clone().into(), Some(inner_order));
+
+        let subquery = Select::from_table(rf.related_model().as_table(ctx))
+            .column(field_col)
+            .so_that(ConditionTree::And(conditions))
+            .order_by(inner_order_def)
+            .limit(1);
+
+        Expression::from(subquery)
+    }
+
+    /// Builds a correlated sub-SELECT for many-to-many relations (via junction table):
+    /// ```sql
+    /// (SELECT field FROM Related
+    ///  INNER JOIN _Junction ON Related.id = _Junction.B
+    ///  WHERE _Junction.A = Parent.id
+    ///  ORDER BY field {dir}
+    ///  LIMIT 1)
+    /// ```
+    fn build_m2m_correlated_subquery(
+        &mut self,
+        rf: &RelationFieldRef,
+        field: &ScalarFieldRef,
+        sort_order: &SortOrder,
+        nulls_order: Option<&NullsOrder>,
+        context_alias: Option<String>,
+        ctx: &Context<'_>,
+    ) -> Expression<'static> {
+        let m2m_table = rf.as_table(ctx);
+        // Column in junction that stores parent IDs (used in WHERE for correlation)
+        let m2m_parent_col = rf.related_field().m2m_column(ctx);
+        // Column in junction that stores child IDs (used in INNER JOIN condition)
+        let m2m_child_col = rf.m2m_column(ctx);
+        let child_model = rf.related_model();
+        let child_ids: ModelProjection = child_model.primary_identifier().into();
+        let parent_ids: ModelProjection = rf.model().primary_identifier().into();
+
+        // WHERE _Junction.parent_col = Parent.id (correlated)
+        let junction_conditions: Vec<Expression<'static>> = parent_ids
+            .scalar_fields()
+            .map(|sf| {
+                let parent_col = sf.as_column(ctx).opt_table(context_alias.clone());
+                let junction_col = m2m_parent_col.clone();
+                junction_col.equals(parent_col).into()
+            })
+            .collect();
+
+        // INNER JOIN _Junction ON Related.id = _Junction.B
+        let left_join_conditions: Vec<Expression<'static>> = child_ids
+            .as_columns(ctx)
+            .map(|c| c.equals(m2m_child_col.clone()).into())
+            .collect();
+
+        let field_col = field.as_column(ctx);
+        // Use the original (non-reversed) direction so LIMIT 1 always picks the
+        // stable representative value for this sort key.
+        let inner_order = into_order(sort_order, nulls_order, false);
+        let inner_order_def: OrderDefinition<'static> = (field_col.clone().into(), Some(inner_order));
+
+        // The WHERE clause already filters to a specific parent via junction_conditions, so
+        // the join on the junction table is effectively mandatory — use an inner join.
+        let subquery = Select::from_table(child_model.as_table(ctx))
+            .column(field_col)
+            .so_that(ConditionTree::And(junction_conditions))
+            .inner_join(m2m_table.on(ConditionTree::And(left_join_conditions)))
+            .order_by(inner_order_def)
+            .limit(1);
+
+        Expression::from(subquery)
+    }
+
     fn compute_joins_aggregation(
         &mut self,
         order_by: &OrderByToManyAggregation,
@@ -154,18 +326,8 @@ impl OrderByBuilder {
         let aggregation_hop = order_by.aggregation_hop();
 
         // Unwraps are safe because the SQL connector doesn't yet support any other type of orderBy hop but the relation hop.
-        let mut joins: Vec<AliasedJoin> = vec![];
-
         let parent_alias = self.parent_alias.clone();
-
-        for (i, hop) in intermediary_hops.iter().enumerate() {
-            let previous_join = if i > 0 { joins.get(i - 1) } else { None };
-
-            let previous_alias = previous_join.map(|j| j.alias.as_str()).or(parent_alias.as_deref());
-            let join = compute_one2m_join(hop.as_relation_hop().unwrap(), &self.join_prefix(), previous_alias, ctx);
-
-            joins.push(join);
-        }
+        let mut joins = self.compute_one2m_join(intermediary_hops, parent_alias.as_ref(), ctx);
 
         let aggregation_type = match order_by.sort_aggregation {
             SortAggregation::Count => AggregationType::Count,

query-compiler/query-builders/sql-query-builder/src/select/mod.rs

@@ -186,10 +186,13 @@ pub(crate) trait JoinSelectBuilder {
             inner.with_columns(selection.into())
         } else {
             // select ordering, distinct, filtering & join fields from child selections to order,
-            // filter & join them on the outer query
+            // filter & join them on the outer query; include linking_fields so that correlated
+            // subqueries built by with_ordering (e.g. for OrderBy::ToManyField) can reference
+            // the parent FK/link columns via inner_alias
             let inner_selection: Vec<Column<'_>> = FieldSelection::union(vec![
                 order_by_selection(rs),
                 distinct_selection(rs),
+                linking_fields,
                 filtering_selection(rs),
                 relation_selection(rs),
             ])
@@ -588,6 +591,10 @@ fn order_by_selection(rs: &RelationSelection) -> FieldSelection {
             // Select the linking fields of the first hop so that the outer select can perform a join to traverse the relation.
             // This is necessary because the order by is done on a different join. The following hops are handled by the order by builder.
             OrderBy::ToManyAggregation(x) => first_hop_linking_fields(x.intermediary_hops()),
+            // For to-many field ordering, project the parent's linking fields (e.g. the PK
+            // referenced by the correlated subquery's WHERE clause) into the inner layer so
+            // that with_ordering can reference them via inner_alias.
+            OrderBy::ToManyField(x) => first_hop_linking_fields(&x.path),
             OrderBy::ScalarAggregation(x) => vec![x.field.clone()],
         })
         .collect();

query-compiler/query-compiler/tests/data/order-by-to-many-1m-field-nulls.json

@@ -0,0 +1,19 @@
+{
+  "modelName": "User",
+  "action": "findMany",
+  "query": {
+    "arguments": {
+      "orderBy": {
+        "posts": {
+          "title": {
+            "sort": "asc",
+            "nulls": "first"
+          }
+        }
+      }
+    },
+    "selection": {
+      "$scalars": true
+    }
+  }
+}

query-compiler/query-compiler/tests/data/order-by-to-many-1m-field.json

@@ -0,0 +1,16 @@
+{
+  "modelName": "User",
+  "action": "findMany",
+  "query": {
+    "arguments": {
+      "orderBy": {
+        "posts": {
+          "title": "asc"
+        }
+      }
+    },
+    "selection": {
+      "$scalars": true
+    }
+  }
+}

query-compiler/query-compiler/tests/data/order-by-to-many-m2m-field.json

@@ -0,0 +1,16 @@
+{
+  "modelName": "Post",
+  "action": "findMany",
+  "query": {
+    "arguments": {
+      "orderBy": {
+        "categories": {
+          "name": "desc"
+        }
+      }
+    },
+    "selection": {
+      "$scalars": true
+    }
+  }
+}

query-compiler/query-compiler/tests/snapshots/queries__queries@nested-distinct-incompatible-orderby-join.json.snap

@@ -21,8 +21,8 @@ process {
           COALESCE(JSONB_AGG("__prisma_data__"), '[]') AS "__prisma_data__" FROM
           (SELECT "t3"."__prisma_data__" FROM (SELECT JSONB_BUILD_OBJECT('id',
           "t2"."id", 'title', "t2"."title") AS "__prisma_data__", "t2"."id",
-          "t2"."title" FROM (SELECT "t1".* FROM "public"."Post" AS "t1" WHERE
-          "t0"."id" = "t1"."userId" /* root select */) AS "t2" /* inner select
-          */) AS "t3" ORDER BY "t3"."id" ASC /* middle select */) AS "t4" /*
-          outer select */) AS "User_posts" ON true»
+          "t2"."title", "t2"."userId" FROM (SELECT "t1".* FROM "public"."Post"
+          AS "t1" WHERE "t0"."id" = "t1"."userId" /* root select */) AS "t2" /*
+          inner select */) AS "t3" ORDER BY "t3"."id" ASC /* middle select */)
+          AS "t4" /* outer select */) AS "User_posts" ON true»
    params [])

query-compiler/query-compiler/tests/snapshots/queries__queries@nested-distinct-join.json.snap

@@ -15,8 +15,8 @@ query «SELECT "t0"."id", "User_posts"."__prisma_data__" AS "posts" FROM
        COALESCE(JSONB_AGG("__prisma_data__"), '[]') AS "__prisma_data__" FROM
        (SELECT DISTINCT ON ("t3"."title") "t3"."__prisma_data__" FROM (SELECT
        JSONB_BUILD_OBJECT('id', "t2"."id", 'title', "t2"."title") AS
-       "__prisma_data__", "t2"."title" FROM (SELECT "t1".* FROM "public"."Post"
-       AS "t1" WHERE "t0"."id" = "t1"."userId" /* root select */) AS "t2" /*
-       inner select */) AS "t3" /* middle select */) AS "t4" /* outer select */)
-       AS "User_posts" ON true»
+       "__prisma_data__", "t2"."title", "t2"."userId" FROM (SELECT "t1".* FROM
+       "public"."Post" AS "t1" WHERE "t0"."id" = "t1"."userId" /* root select
+       */) AS "t2" /* inner select */) AS "t3" /* middle select */) AS "t4" /*
+       outer select */) AS "User_posts" ON true»
 params []

query-compiler/query-compiler/tests/snapshots/queries__queries@nested-distinct-orderby-join.json.snap

@@ -15,8 +15,8 @@ query «SELECT "t0"."id", "User_posts"."__prisma_data__" AS "posts" FROM
        COALESCE(JSONB_AGG("__prisma_data__"), '[]') AS "__prisma_data__" FROM
        (SELECT DISTINCT ON ("t3"."title") "t3"."__prisma_data__" FROM (SELECT
        JSONB_BUILD_OBJECT('id', "t2"."id", 'title', "t2"."title") AS
-       "__prisma_data__", "t2"."title" FROM (SELECT "t1".* FROM "public"."Post"
-       AS "t1" WHERE "t0"."id" = "t1"."userId" /* root select */) AS "t2" /*
-       inner select */) AS "t3" ORDER BY "t3"."title" ASC /* middle select */)
-       AS "t4" /* outer select */) AS "User_posts" ON true»
+       "__prisma_data__", "t2"."title", "t2"."userId" FROM (SELECT "t1".* FROM
+       "public"."Post" AS "t1" WHERE "t0"."id" = "t1"."userId" /* root select
+       */) AS "t2" /* inner select */) AS "t3" ORDER BY "t3"."title" ASC /*
+       middle select */) AS "t4" /* outer select */) AS "User_posts" ON true»
 params []