Include child records in queries

Goal

Fetch child records alongside a parent in a single HOQS query, optionally filtered, sorted, and nested.

Prerequisites

• A relationship exists whose inverse (toInverseKey) names the children you want to fetch. See Relationships and Lookups.
• You can already run a basic query — see Query and filter records.

Steps

1. Add a bare INCLUDE

The relationship name comes from the lookup’s toInverseKey — for example, if Contact has a lookup to Account with toInverseKey: "contacts", you can include contacts when querying accounts:

SELECT name, industry FROM core.Account
INCLUDE contacts
LIMIT 10

Each Account in the result has a contacts array with the matching child records.

2. Filter, select fields, sort, and limit within the INCLUDE

SELECT name FROM core.Account
INCLUDE contacts (firstName, email) WHERE status = 'active' ORDER BY lastName ASC LIMIT 5
LIMIT 10

3. Nest INCLUDEs for multiple levels

SELECT name FROM core.Account
INCLUDE contacts
  INCLUDE opportunities WHERE stage = 'Closed Won' LIMIT 10
LIMIT 10

This returns Accounts with their Contacts, and each Contact carries its own Opportunities. Nesting depth is limited to 3 levels.

Verification

Check that each parent record in data carries the included relationship as a nested array, and that any WHERE/ORDER BY/LIMIT you added inside the INCLUDE clause is reflected in that array (not the top-level result set).

See also

• Querying Data with HOQS – why INCLUDE issues a query per parent row instead of a SQL JOIN, and why nesting is capped at 3 levels
• Query and filter records
• HOQS Query Language Reference – full INCLUDE grammar and limits