GraphQL Relationship Traversal

introduction nue's graphql api lets you follow relationships between objects directly in a single query, instead of issuing multiple calls and stitching the results together on the client side this makes it possible to answer relationship questions — such as "what price book does this product belong to?" or "which price tags reference this product?" — in one round trip wherever an object has a lookup to another object, nue exposes both the scalar foreign key field (for example, pricebookid ), and a nested relation field that returns the related object (for example, pricebook ) you can select the scalar id when you only need the reference, or expand the nested field when you need data from the related object nested lookups a nested lookup follows a forward relationship (a lookup field) to the object it points to select the nested relation field and choose the fields you want from the related object the example below queries products and, for each one, expands its price book and default unit of measure query { product(page { cursor 0, limit 5 }) { id name pricebookid pricebook { id name } defaultuomid defaultuom { id name } } } the scalar pricebookid and the nested pricebook id refer to the same record, so you can rely on either depending on how much related data you need nested lookups are available wherever a lookup exists for example, a price dimension can expand its price book, unit of measure, and product query { pricedimension(page { cursor 0, limit 5 }) { id pricebookid pricebook { id name } uomid uom { id name } productid product { id name } } } reverse relations a reverse relation follows a relationship in the opposite direction — from a parent object to the collection of records that point back to it for example, a product exposes the price tags and bundle options that reference it query { product( where { configurable { eq true } } page { cursor 0, limit 5 } ) { id name pricetags { id } productoptions { id } } } reverse relations are themselves collections, so they accept the same arguments as top level queries — where , orderby , and page — letting you filter, sort, and paginate the related records the exact nested and reverse relation field names available on an object depend on its configuration use schema introspection (see query nue objects using graphql docid 9j6pcigzvpcgzsdikcwc ) to confirm the relation fields exposed for a given object in your org traversal depth relationship traversal is limited to a maximum depth of 3 levels a query that stays within three levels of nesting succeeds query { pricedimension(page { cursor 0, limit 1 }) { id pricebook { id name } } } queries that nest more deeply than three levels are rejected keep traversals shallow and run a follow up query if you need data that sits deeper in the graph traversing across services relationship traversal works within a single service cpq objects (such as product and pricedimension ) can expand their cpq relationships, and order objects (such as subscription and invoice ) can expand their order relationships nesting that crosses the boundary between the cpq and order services in one raw graphql query — for example, expanding subscription customer and subscription product together when the objects live on different endpoints — is not supported and will return an error to answer questions that span both services, use the natural language interface, which plans and joins across services for you see querying nue with natural language docid\ fx1sinxmvaq9xuyydlcwn for cross service questions such as "which customers have an active subscription to product x and an overdue invoice?" related guides query nue objects using graphql docid 9j6pcigzvpcgzsdikcwc — endpoints, supported objects, filtering, pagination, and introspection graphql aggregations docid\ wxok4pxgwzyfbo4ici2zl — count , sum , avg , min , max , and groupby rollups