Skip to main content

ruprizzle/
include.rs

1//! Batched relation `include` loading.
2
3use std::collections::{HashMap, HashSet};
4use std::fmt;
5use std::hash::Hash;
6use std::marker::PhantomData;
7
8use crate::BoxFuture;
9use crate::col::Column;
10use crate::compile::select_partitioned;
11use crate::error::Error;
12use crate::executor::Executor;
13use crate::filter::Filter;
14use crate::model::Model;
15use crate::order::OrderBy;
16use crate::query::SelectQuery;
17use crate::related::Related;
18use crate::value::Encodable;
19
20/// Loads every child row belonging to any of `keys`, in a bounded number of
21/// queries.
22///
23/// `limit` is a **per-parent** limit, not a limit on the batch: `take(5)` means
24/// five children for each parent, which is what the caller asked for and what a
25/// plain `LIMIT` would silently fail to deliver. It is compiled to a
26/// `ROW_NUMBER() OVER (PARTITION BY ...)` window; only if the dialect cannot do
27/// windows does this degrade to one query per parent.
28async fn fetch_children<C, Key>(
29    exec: &dyn Executor,
30    child_key: Column<C, Key>,
31    filter: &Filter<C>,
32    order: &[OrderBy<C>],
33    limit: Option<u64>,
34    keys: &[Key],
35    full_table: bool,
36) -> Result<Vec<C>, Error>
37where
38    C: Model + Send + Unpin,
39    Key: Encodable + Eq + Hash + Clone + Send + Sync + 'static,
40{
41    // Fast path: if the parent set is the whole parent table and the child
42    // include has no extra filter, order or per-parent limit, we can avoid
43    // parsing and binding a large `IN` list by loading the whole child table.
44    // To prevent unbounded materialisation when the child table is huge, we
45    // first COUNT(*) it and fall back to chunked `IN` above the executor's
46    // limit. `0` disables the fast path entirely.
47    let full_table_limit = exec.full_table_include_limit();
48    if full_table
49        && full_table_limit > 0
50        && filter.node == crate::filter::FilterNode::And(Vec::new())
51        && order.is_empty()
52        && limit.is_none()
53    {
54        let child_count = SelectQuery::<C>::new(exec).count().await?;
55        if child_count <= full_table_limit as i64 {
56            return SelectQuery::<C>::new(exec).fetch_all().await;
57        }
58    }
59
60    // The parent set repeats keys whenever several parents point at the same
61    // child (every many-to-one relation does). Sending the duplicates would
62    // inflate the `IN` list and burn the parameter budget for nothing. The
63    // dedup set borrows the keys so we avoid cloning every parent key just to
64    // spot duplicates.
65    let keys = dedup(keys);
66    if keys.is_empty() {
67        return Ok(Vec::new());
68    }
69
70    let dialect = exec.dialect();
71    let caps = dialect.capabilities();
72    // Leave headroom for the binds the relation filter itself contributes.
73    let chunk_size = (caps.max_query_params as usize).saturating_sub(10).max(1);
74
75    if let Some(n) = limit {
76        if !caps.window_functions {
77            return fetch_children_per_parent(exec, child_key, filter, order, n, &keys).await;
78        }
79
80        let mut all = Vec::new();
81        for chunk in keys.chunks(chunk_size) {
82            // This path compiles its own SQL instead of going through
83            // `SelectQuery`, so it must add the soft-delete predicate itself.
84            let combined = filter
85                .clone()
86                .and(crate::model::live_rows::<C>())
87                .and(child_key.in_set(chunk.iter().copied().cloned().collect::<Vec<_>>()));
88            let compiled = select_partitioned::<C>(
89                dialect,
90                C::TABLE,
91                child_key.column,
92                &combined.node,
93                order,
94                n,
95            );
96            let batch = exec.fetch_all_raw(compiled.sql, compiled.binds).await?;
97            all.extend(crate::executor::decode_rows::<C>(batch)?);
98        }
99        return Ok(all);
100    }
101
102    let mut all = Vec::new();
103    for chunk in keys.chunks(chunk_size) {
104        let mut q = SelectQuery::<C>::new(exec)
105            .filter(child_key.in_set(chunk.iter().copied().cloned().collect::<Vec<_>>()));
106        if filter.node != crate::filter::FilterNode::And(Vec::new()) {
107            q = q.filter(filter.clone());
108        }
109        for o in order {
110            q = q.order_by(o.clone());
111        }
112        all.extend(q.fetch_all().await?);
113    }
114    Ok(all)
115}
116
117/// The no-window-function fallback: one `LIMIT`ed query per parent key.
118///
119/// Correct, but linear in the parent count — the very shape the batched loader
120/// exists to avoid. No dialect shipped today takes this path.
121async fn fetch_children_per_parent<C, Key>(
122    exec: &dyn Executor,
123    child_key: Column<C, Key>,
124    filter: &Filter<C>,
125    order: &[OrderBy<C>],
126    limit: u64,
127    keys: &[&Key],
128) -> Result<Vec<C>, Error>
129where
130    C: Model + Send + Unpin,
131    Key: Encodable + Clone + Send + Sync + 'static,
132{
133    let mut all = Vec::new();
134    for key in keys {
135        let mut q = SelectQuery::<C>::new(exec).filter(child_key.eq((*key).clone()));
136        if filter.node != crate::filter::FilterNode::And(Vec::new()) {
137            q = q.filter(filter.clone());
138        }
139        for o in order {
140            q = q.order_by(o.clone());
141        }
142        all.extend(q.limit(limit).fetch_all().await?);
143    }
144    Ok(all)
145}
146
147/// Removes duplicates while keeping first-seen order.
148///
149/// Borrows from `keys` so the deduplication set does not clone every key; the
150/// caller clones only the keys it actually uses in `IN`/`=` binds.
151fn dedup<Key: Eq + Hash>(keys: &[Key]) -> Vec<&Key> {
152    let mut seen = HashSet::with_capacity(keys.len());
153    keys.iter().filter(|k| seen.insert(*k)).collect()
154}
155
156/// A set of includes to attach to a parent model.
157///
158/// This is a type-level "list": a single relation implements it, and nested
159/// relations are chained through the relation builder's own `.include()` method.
160pub trait IncludeSet<M: Model> {
161    /// Loads the related data and attaches it to `parents` in place.
162    ///
163    /// `full_table` is `true` when the parent query is known to load every row
164    /// of the parent table with no filter, limit, offset or distinct. Loaders
165    /// can use this to fetch the whole child table instead of building an `IN`
166    /// list of parent keys.
167    fn load<'a>(
168        &'a self,
169        exec: &'a dyn Executor,
170        parents: &'a mut [M],
171        full_table: bool,
172    ) -> BoxFuture<'a, Result<(), Error>>;
173}
174
175impl<M: Model> IncludeSet<M> for () {
176    fn load<'a>(
177        &'a self,
178        _exec: &'a dyn Executor,
179        _parents: &'a mut [M],
180        _full_table: bool,
181    ) -> BoxFuture<'a, Result<(), Error>> {
182        Box::pin(async { Ok(()) })
183    }
184}
185
186/// Include a one-to-many relation (parent has many children).
187pub struct IncludeList<'db, M, C, Key, NI = ()> {
188    /// Extract the join key from the parent.
189    pub get: fn(&M) -> Key,
190    /// Attach the loaded children to the parent.
191    pub set: fn(&mut M, Related<Vec<C>>),
192    /// The child column that matches the parent key.
193    pub child_key: Column<C, Key>,
194    /// Extract the join key from a child row.
195    pub child_key_get: fn(&C) -> Key,
196    /// Optional extra filter on the child rows.
197    pub filter: Filter<C>,
198    /// Ordering for the child rows.
199    pub order: Vec<OrderBy<C>>,
200    /// Optional per-child limit (`take`).
201    pub limit: Option<u64>,
202    /// Nested includes on the child.
203    pub nested: NI,
204    _marker: PhantomData<fn() -> &'db ()>,
205}
206
207impl<'db, M, C, Key, NI> Clone for IncludeList<'db, M, C, Key, NI>
208where
209    NI: Clone,
210{
211    fn clone(&self) -> Self {
212        Self {
213            get: self.get,
214            set: self.set,
215            child_key: self.child_key,
216            child_key_get: self.child_key_get,
217            filter: self.filter.clone(),
218            order: self.order.clone(),
219            limit: self.limit,
220            nested: self.nested.clone(),
221            _marker: PhantomData,
222        }
223    }
224}
225
226impl<'db, M, C, Key, NI> fmt::Debug for IncludeList<'db, M, C, Key, NI>
227where
228    NI: fmt::Debug,
229{
230    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
231        f.debug_struct("IncludeList")
232            .field("child_key", &self.child_key)
233            .field("filter", &self.filter)
234            .field("order", &self.order)
235            .field("limit", &self.limit)
236            .field("nested", &self.nested)
237            .finish()
238    }
239}
240
241impl<'db, M, C, Key> IncludeList<'db, M, C, Key, ()>
242where
243    M: Model,
244    C: Model,
245{
246    /// Creates a new one-to-many include.
247    pub const fn new(
248        get: fn(&M) -> Key,
249        set: fn(&mut M, Related<Vec<C>>),
250        child_key: Column<C, Key>,
251        child_key_get: fn(&C) -> Key,
252    ) -> Self {
253        Self {
254            get,
255            set,
256            child_key,
257            child_key_get,
258            filter: Filter::new(crate::filter::FilterNode::And(Vec::new())),
259            order: Vec::new(),
260            limit: None,
261            nested: (),
262            _marker: PhantomData,
263        }
264    }
265}
266
267impl<'db, M, C, Key, NI> IncludeList<'db, M, C, Key, NI>
268where
269    M: Model,
270    C: Model,
271{
272    /// Adds an extra filter on the child rows.
273    pub fn filter(mut self, f: Filter<C>) -> Self {
274        self.filter = self.filter.and(f);
275        self
276    }
277
278    /// Adds a child ordering.
279    pub fn order_by(mut self, o: OrderBy<C>) -> Self {
280        self.order.push(o);
281        self
282    }
283
284    /// Limits the number of children per parent.
285    pub fn take(mut self, n: u64) -> Self {
286        self.limit = Some(n);
287        self
288    }
289
290    /// Adds a nested include on the child.
291    pub fn include<J: IncludeSet<C>>(self, include: J) -> IncludeList<'db, M, C, Key, J> {
292        IncludeList {
293            get: self.get,
294            set: self.set,
295            child_key: self.child_key,
296            child_key_get: self.child_key_get,
297            filter: self.filter,
298            order: self.order,
299            limit: self.limit,
300            nested: include,
301            _marker: PhantomData,
302        }
303    }
304}
305
306impl<'db, M, C, Key, NI> IncludeSet<M> for IncludeList<'db, M, C, Key, NI>
307where
308    M: Model + Send + Unpin,
309    // `Clone` because a one-to-many relation is one-to-many: when several parents
310    // share a join key, the same child row must appear in each parent's `Vec`.
311    C: Model + Clone + Send + Unpin,
312    Key: Encodable + Eq + Hash + Clone + Send + Sync + 'static,
313    NI: IncludeSet<C> + Sync,
314{
315    fn load<'a>(
316        &'a self,
317        exec: &'a dyn Executor,
318        parents: &'a mut [M],
319        full_table: bool,
320    ) -> BoxFuture<'a, Result<(), Error>> {
321        Box::pin(async move {
322            if parents.is_empty() {
323                return Ok(());
324            }
325
326            let keys: Vec<Key> = parents.iter().map(self.get).collect();
327            let mut children = fetch_children(
328                exec,
329                self.child_key,
330                &self.filter,
331                &self.order,
332                self.limit,
333                &keys,
334                full_table,
335            )
336            .await?;
337
338            // Propagate the full-table hint to nested includes if this child
339            // query was itself an unconstrained full-table fetch.
340            let child_full_table = full_table
341                && self.filter.node == crate::filter::FilterNode::And(Vec::new())
342                && self.order.is_empty()
343                && self.limit.is_none();
344            self.nested
345                .load(exec, &mut children, child_full_table)
346                .await?;
347
348            // Group children into pre-sized buckets indexed by parent position.
349            // A parent key can map to more than one parent when the join key is not
350            // unique, so the index keeps a list of parent positions and a child is
351            // cloned into every matching bucket. The single-parent case avoids a
352            // clone.
353            let bucket_hint = children.len() / parents.len();
354            let mut parent_index: HashMap<Key, Vec<usize>> = HashMap::with_capacity(parents.len());
355            for (i, parent) in parents.iter().enumerate() {
356                parent_index.entry((self.get)(parent)).or_default().push(i);
357            }
358
359            let mut buckets: Vec<Vec<C>> =
360                std::iter::repeat_with(|| Vec::with_capacity(bucket_hint))
361                    .take(parents.len())
362                    .collect();
363
364            for child in children {
365                if let Some(indices) = parent_index.get(&(self.child_key_get)(&child)) {
366                    let mut iter = indices.iter();
367                    if let Some(&first) = iter.next() {
368                        // Clone only for additional parents; the first gets the
369                        // original child.
370                        for &idx in iter {
371                            if let Some(bucket) = buckets.get_mut(idx) {
372                                bucket.push(child.clone());
373                            }
374                        }
375                        if let Some(bucket) = buckets.get_mut(first) {
376                            bucket.push(child);
377                        }
378                    }
379                }
380            }
381
382            for (parent, bucket) in parents.iter_mut().zip(buckets) {
383                (self.set)(parent, Related::Loaded(bucket));
384            }
385
386            Ok(())
387        })
388    }
389}
390
391/// Include a many-to-one / one-to-one relation (parent has one child).
392pub struct IncludeOne<'db, M, C, Key, NI = ()> {
393    /// Extract the join key from the parent.
394    pub get: fn(&M) -> Key,
395    /// Attach the loaded child to the parent.
396    pub set: fn(&mut M, Related<Option<C>>),
397    /// The child column that matches the parent key.
398    pub child_key: Column<C, Key>,
399    /// Extract the join key from a child row.
400    pub child_key_get: fn(&C) -> Key,
401    /// Optional extra filter on the child rows.
402    pub filter: Filter<C>,
403    /// Ordering for the child rows.
404    pub order: Vec<OrderBy<C>>,
405    /// Optional per-child limit (`take`).
406    pub limit: Option<u64>,
407    /// Nested includes on the child.
408    pub nested: NI,
409    _marker: PhantomData<fn() -> &'db ()>,
410}
411
412impl<'db, M, C, Key, NI> Clone for IncludeOne<'db, M, C, Key, NI>
413where
414    NI: Clone,
415{
416    fn clone(&self) -> Self {
417        Self {
418            get: self.get,
419            set: self.set,
420            child_key: self.child_key,
421            child_key_get: self.child_key_get,
422            filter: self.filter.clone(),
423            order: self.order.clone(),
424            limit: self.limit,
425            nested: self.nested.clone(),
426            _marker: PhantomData,
427        }
428    }
429}
430
431impl<'db, M, C, Key, NI> fmt::Debug for IncludeOne<'db, M, C, Key, NI>
432where
433    NI: fmt::Debug,
434{
435    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
436        f.debug_struct("IncludeOne")
437            .field("child_key", &self.child_key)
438            .field("filter", &self.filter)
439            .field("order", &self.order)
440            .field("limit", &self.limit)
441            .field("nested", &self.nested)
442            .finish()
443    }
444}
445
446impl<'db, M, C, Key> IncludeOne<'db, M, C, Key, ()>
447where
448    M: Model,
449    C: Model,
450{
451    /// Creates a new many-to-one / one-to-one include.
452    pub const fn new(
453        get: fn(&M) -> Key,
454        set: fn(&mut M, Related<Option<C>>),
455        child_key: Column<C, Key>,
456        child_key_get: fn(&C) -> Key,
457    ) -> Self {
458        Self {
459            get,
460            set,
461            child_key,
462            child_key_get,
463            filter: Filter::new(crate::filter::FilterNode::And(Vec::new())),
464            order: Vec::new(),
465            limit: None,
466            nested: (),
467            _marker: PhantomData,
468        }
469    }
470}
471
472impl<'db, M, C, Key, NI> IncludeOne<'db, M, C, Key, NI>
473where
474    M: Model,
475    C: Model,
476{
477    /// Adds an extra filter on the child rows.
478    pub fn filter(mut self, f: Filter<C>) -> Self {
479        self.filter = self.filter.and(f);
480        self
481    }
482
483    /// Adds a child ordering.
484    pub fn order_by(mut self, o: OrderBy<C>) -> Self {
485        self.order.push(o);
486        self
487    }
488
489    /// Limits the number of children (normally 1 for a single relation).
490    pub fn take(mut self, n: u64) -> Self {
491        self.limit = Some(n);
492        self
493    }
494
495    /// Adds a nested include on the child.
496    pub fn include<J: IncludeSet<C>>(self, include: J) -> IncludeOne<'db, M, C, Key, J> {
497        IncludeOne {
498            get: self.get,
499            set: self.set,
500            child_key: self.child_key,
501            child_key_get: self.child_key_get,
502            filter: self.filter,
503            order: self.order,
504            limit: self.limit,
505            nested: include,
506            _marker: PhantomData,
507        }
508    }
509}
510
511/// Include a many-to-many relation that traverses an explicit join model.
512///
513/// Loads the join rows and the target rows in two batched queries, then
514/// distributes target rows back to each parent by matching the join keys.
515pub struct IncludeMany<'db, M, C, J, Key, CKey, NI = ()> {
516    /// Extract the parent key from the parent row.
517    pub get: fn(&M) -> Key,
518    /// Attach the loaded children to the parent.
519    pub set: fn(&mut M, Related<Vec<C>>),
520    /// Extract the parent key from a join row.
521    pub join_owner_get: fn(&J) -> Key,
522    /// Extract the target key from a join row.
523    pub join_target_get: fn(&J) -> CKey,
524    /// Extract the target key from a child row.
525    pub child_key_get: fn(&C) -> CKey,
526    /// The join column that stores the parent key.
527    pub join_owner_col: Column<J, Key>,
528    /// The join column that stores the target key.
529    pub join_target_col: Column<J, CKey>,
530    /// The target primary key column.
531    pub target_pk: Column<C, CKey>,
532    /// Optional extra filter on the target rows.
533    pub filter: Filter<C>,
534    /// Ordering for the target rows.
535    pub order: Vec<OrderBy<C>>,
536    /// Optional per-parent limit (`take`).
537    pub limit: Option<u64>,
538    /// Nested includes on the target.
539    pub nested: NI,
540    _marker: PhantomData<fn() -> &'db ()>,
541}
542
543impl<'db, M, C, J, Key, CKey, NI> Clone for IncludeMany<'db, M, C, J, Key, CKey, NI>
544where
545    NI: Clone,
546{
547    fn clone(&self) -> Self {
548        Self {
549            get: self.get,
550            set: self.set,
551            join_owner_get: self.join_owner_get,
552            join_target_get: self.join_target_get,
553            child_key_get: self.child_key_get,
554            join_owner_col: self.join_owner_col,
555            join_target_col: self.join_target_col,
556            target_pk: self.target_pk,
557            filter: self.filter.clone(),
558            order: self.order.clone(),
559            limit: self.limit,
560            nested: self.nested.clone(),
561            _marker: PhantomData,
562        }
563    }
564}
565
566impl<'db, M, C, J, Key, CKey> IncludeMany<'db, M, C, J, Key, CKey, ()>
567where
568    M: Model,
569    C: Model,
570    J: Model,
571{
572    /// Creates a new many-to-many include.
573    #[allow(clippy::too_many_arguments)]
574    pub const fn new(
575        get: fn(&M) -> Key,
576        set: fn(&mut M, Related<Vec<C>>),
577        join_owner_get: fn(&J) -> Key,
578        join_target_get: fn(&J) -> CKey,
579        child_key_get: fn(&C) -> CKey,
580        join_owner_col: Column<J, Key>,
581        join_target_col: Column<J, CKey>,
582        target_pk: Column<C, CKey>,
583    ) -> Self {
584        Self {
585            get,
586            set,
587            join_owner_get,
588            join_target_get,
589            child_key_get,
590            join_owner_col,
591            join_target_col,
592            target_pk,
593            filter: Filter::new(crate::filter::FilterNode::And(Vec::new())),
594            order: Vec::new(),
595            limit: None,
596            nested: (),
597            _marker: PhantomData,
598        }
599    }
600}
601
602impl<'db, M, C, J, Key, CKey, NI> IncludeMany<'db, M, C, J, Key, CKey, NI>
603where
604    M: Model,
605    C: Model,
606    J: Model,
607{
608    /// Adds an extra filter on the target rows.
609    pub fn filter(mut self, f: Filter<C>) -> Self {
610        self.filter = self.filter.and(f);
611        self
612    }
613
614    /// Adds a target ordering.
615    pub fn order_by(mut self, o: OrderBy<C>) -> Self {
616        self.order.push(o);
617        self
618    }
619
620    /// Limits the number of target rows per parent.
621    pub fn take(mut self, n: u64) -> Self {
622        self.limit = Some(n);
623        self
624    }
625
626    /// Adds a nested include on the target.
627    pub fn include<Next: IncludeSet<C>>(
628        self,
629        include: Next,
630    ) -> IncludeMany<'db, M, C, J, Key, CKey, Next> {
631        IncludeMany {
632            get: self.get,
633            set: self.set,
634            join_owner_get: self.join_owner_get,
635            join_target_get: self.join_target_get,
636            child_key_get: self.child_key_get,
637            join_owner_col: self.join_owner_col,
638            join_target_col: self.join_target_col,
639            target_pk: self.target_pk,
640            filter: self.filter,
641            order: self.order,
642            limit: self.limit,
643            nested: include,
644            _marker: PhantomData,
645        }
646    }
647}
648
649impl<'db, M, C, J, Key, CKey, NI> IncludeSet<M> for IncludeMany<'db, M, C, J, Key, CKey, NI>
650where
651    M: Model + Send + Unpin,
652    C: Model + Clone + Send + Unpin,
653    J: Model + Send + Unpin,
654    Key: Encodable + Eq + Hash + Clone + Send + Sync + 'static,
655    CKey: Encodable + Eq + Hash + Clone + Send + Sync + 'static,
656    NI: IncludeSet<C> + Sync,
657{
658    fn load<'a>(
659        &'a self,
660        exec: &'a dyn Executor,
661        parents: &'a mut [M],
662        _full_table: bool,
663    ) -> BoxFuture<'a, Result<(), Error>> {
664        Box::pin(async move {
665            if parents.is_empty() {
666                return Ok(());
667            }
668
669            let keys: Vec<Key> = parents.iter().map(self.get).collect();
670            let deduped = dedup(&keys);
671            let caps = exec.dialect().capabilities();
672            let chunk_size = (caps.max_query_params as usize).saturating_sub(10).max(1);
673
674            // 1. Load the join rows for all parents in chunked `IN` queries.
675            let mut join_rows: Vec<J> = Vec::new();
676            for chunk in deduped.chunks(chunk_size) {
677                let values: Vec<Key> = chunk.iter().copied().cloned().collect();
678                let q = SelectQuery::<J>::new(exec)
679                    .filter(self.join_owner_col.in_set(values))
680                    .order_by(self.join_owner_col.asc())
681                    .order_by(self.join_target_col.asc());
682                join_rows.extend(q.fetch_all().await?);
683            }
684
685            if join_rows.is_empty() {
686                for parent in parents.iter_mut() {
687                    (self.set)(parent, Related::Loaded(Vec::new()));
688                }
689                return Ok(());
690            }
691
692            // 2. Collect the unique target keys referenced by the join rows.
693            let child_keys: Vec<CKey> = join_rows
694                .iter()
695                .map(|j| (self.join_target_get)(j))
696                .collect();
697            let child_keys = dedup(&child_keys).into_iter().cloned().collect::<Vec<_>>();
698
699            // 3. Load the target rows in one (possibly chunked) query,
700            //    applying the user filter and order.
701            let mut children: Vec<C> = Vec::new();
702            for chunk in child_keys.chunks(chunk_size) {
703                let values: Vec<CKey> = chunk.to_vec();
704                let mut q = SelectQuery::<C>::new(exec).filter(self.target_pk.in_set(values));
705                if self.filter.node != crate::filter::FilterNode::And(Vec::new()) {
706                    q = q.filter(self.filter.clone());
707                }
708                for o in &self.order {
709                    q = q.order_by(o.clone());
710                }
711                children.extend(q.fetch_all().await?);
712            }
713
714            // 4. Recursively load nested includes on the target rows.
715            self.nested.load(exec, &mut children, false).await?;
716
717            // 5. Build a parent key -> [parent index] map.
718            let mut parent_index: HashMap<Key, Vec<usize>> = HashMap::with_capacity(parents.len());
719            for (i, parent) in parents.iter().enumerate() {
720                parent_index.entry((self.get)(parent)).or_default().push(i);
721            }
722
723            // 6. Map each target key to the parent indices that reference it.
724            let mut child_to_parents: HashMap<CKey, Vec<usize>> =
725                HashMap::with_capacity(join_rows.len());
726            for j in &join_rows {
727                let owner = (self.join_owner_get)(j);
728                if let Some(indices) = parent_index.get(&owner) {
729                    let target = (self.join_target_get)(j);
730                    child_to_parents
731                        .entry(target)
732                        .or_default()
733                        .extend(indices.iter().copied());
734                }
735            }
736
737            // 7. Walk the target rows in the requested order and distribute
738            //    them to the matching parent buckets.
739            let mut buckets: Vec<Vec<C>> = std::iter::repeat_with(Vec::new)
740                .take(parents.len())
741                .collect();
742            for child in children {
743                let target_key = (self.child_key_get)(&child);
744                if let Some(parents) = child_to_parents.get(&target_key) {
745                    for &idx in parents {
746                        buckets[idx].push(child.clone());
747                    }
748                }
749            }
750
751            // 8. Apply per-parent take and attach.
752            for (parent, mut bucket) in parents.iter_mut().zip(buckets) {
753                if let Some(n) = self.limit {
754                    let n = n as usize;
755                    if bucket.len() > n {
756                        bucket.truncate(n);
757                    }
758                }
759                (self.set)(parent, Related::Loaded(bucket));
760            }
761
762            Ok(())
763        })
764    }
765}
766
767impl<'db, M, C, Key, NI> IncludeSet<M> for IncludeOne<'db, M, C, Key, NI>
768where
769    M: Model + Send + Unpin,
770    C: Model + Clone + Send + Unpin,
771    Key: Encodable + Eq + Hash + Clone + Send + Sync + 'static,
772    NI: IncludeSet<C> + Sync,
773{
774    fn load<'a>(
775        &'a self,
776        exec: &'a dyn Executor,
777        parents: &'a mut [M],
778        full_table: bool,
779    ) -> BoxFuture<'a, Result<(), Error>> {
780        Box::pin(async move {
781            if parents.is_empty() {
782                return Ok(());
783            }
784
785            let keys: Vec<Key> = parents.iter().map(self.get).collect();
786            let mut children = fetch_children(
787                exec,
788                self.child_key,
789                &self.filter,
790                &self.order,
791                self.limit,
792                &keys,
793                full_table,
794            )
795            .await?;
796
797            let child_full_table = full_table
798                && self.filter.node == crate::filter::FilterNode::And(Vec::new())
799                && self.order.is_empty()
800                && self.limit.is_none();
801            self.nested
802                .load(exec, &mut children, child_full_table)
803                .await?;
804
805            let mut map: HashMap<Key, C> = HashMap::with_capacity(parents.len());
806            for child in children {
807                let key = (self.child_key_get)(&child);
808                if let std::collections::hash_map::Entry::Vacant(e) = map.entry(key) {
809                    e.insert(child);
810                }
811            }
812
813            for parent in parents.iter_mut() {
814                let key = (self.get)(parent);
815                let related = Related::Loaded(map.get(&key).cloned());
816                (self.set)(parent, related);
817            }
818
819            Ok(())
820        })
821    }
822}