GraphQL Relationship Traversal

8 min

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 GraphQLQuery Nue Objects using GraphQL) 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 LanguageQuerying Nue with Natural Language for cross-service questions such as "which customers have an active subscription to Product X and an overdue invoice?"

Query Nue Objects using GraphQLQuery Nue Objects using GraphQL — endpoints, supported objects, filtering, pagination, and introspection.

GraphQL AggregationsGraphQL Aggregations — count, sum, avg, min, max, and groupBy rollups.