---
title: GraphQL Relationship Traversal
slug: graphql-relationship-traversal
docTags: 
createdAt: 2026-06-13T01:56:04.473Z
---

# 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:

```graphql
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:

```graphql
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:

```graphql
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.

:::hint{type="info"}
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:

```graphql
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:

:::hint{type="info"}
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.