How do I avoid N+1 queries when loading relations?

[coenddt]

Documenting this here because it comes up often — if your situation is different, please reply in this thread.

Right now I load the parents, collect their ids, then issue a second query per relation to group the children back myself. It works, but it is a lot of glue code that has to be repeated for every relation.

[coenddt]

Declare the relation in the schema and select it in the GQL body — you never hand-write $lookup or a JOIN.

store.register({
  name: 'Order', collection: 'orders',
  fields: { code: { type: 'string' } },
  relations: {
    items: { model: 'OrderItem', type: 'many', localField: '_id', foreignField: 'orderId' },
  },
});

const rows = await store.query(
  'Order($condition:@c0,$limit:@l) { code, items($sort:@s1,$limit:@l2) { sku, qty } }',
  { c0: { status: 'paid' }, l: 50, s1: { qty: -1 }, l2: 5 },
);

Relations compile to $lookup / $addFields on MongoDB, and to a JOIN when the backend is relational. You build the tree once and the engine resolves it as part of one plan.

Two limits worth knowing before you design around it:

• Per-parent top-N inside a relation is not always pushable. "The 5 most recent items for each order" is one of the combinations the SQL dialects cannot express safely, so the engine marks it unsupported instead of silently returning the global top 5.
• Two-phase plans exist for a reason. When a relation carries both a filter and pagination, the read path becomes two commands (take the parent ids first, then join) — the host is expected to execute both, in order.

Walkthrough: https://coenddt.github.io/nodejs-store/use-cases/05-avoiding-n-plus-one-reads.html