Relations Decorator

Resolver param decorator which returns an array of relation paths which can be passed through to the TypeORM data layer in order to join only the required relations. This works by inspecting the GraphQL info object, examining the field selection, and then comparing this with information about the return type's relations.

In addition to analyzing the field selection, this decorator also checks for any @Calculated() properties on the entity, and additionally includes relations from the relations array of the calculated metadata, if defined.

So if, for example, the query only selects the id field of an Order, then no other relations need be joined in the resulting SQL query. This can massively speed up execution time for queries which do not include many deep nested relations.

Example

@Query()@Allow(Permission.ReadOrder)orders(    @Ctx() ctx: RequestContext,    @Args() args: QueryOrdersArgs,    @Relations(Order) relations: RelationPaths<Order>,): Promise<PaginatedList<Order>> {    return this.orderService.findAll(ctx, args.options || undefined, relations);}

In the above example, given the following query:

Example

{  orders(options: { take: 10 }) {    items {      id      customer {        id        firstName        lastName      }      totalQuantity      totalWithTax    }  }}

then the value of relations will be

['customer', 'lines'']

The 'customer' comes from the fact that the query is nesting the "customer" object, and the 'lines' is taken from the Order entity's totalQuantity property, which uses Calculated decorator and defines those relations as dependencies for deriving the calculated value.

Depth

By default, when inspecting the GraphQL query, the Relations decorator will look 3 levels deep in any nested fields. So, e.g. if the above orders query were changed to:

Example

{  orders(options: { take: 10 }) {    items {      id      lines {        productVariant {          product {            featuredAsset {              preview            }          }        }      }    }  }}

then the relations array would include 'lines', 'lines.productVariant', & 'lines.productVariant.product' - 3 levels deep - but it would not include 'lines.productVariant.product.featuredAsset' since that exceeds the default depth. To specify a custom depth, you would use the decorator like this:

Example

@Relations({ entity: Order, depth: 2 }) relations: RelationPaths<Order>,

Omit

The omit option is used to explicitly omit certain relations from the calculated relations array. This is useful in certain cases where we know for sure that we need to run the field resolver anyway. A good example is the Collection.productVariants relation. When a GraphQL query comes in for a Collection and also requests its productVariants field, there is no point using a lookahead to eagerly join that relation, because we will throw that data away anyway when the productVariants field resolver executes, since it returns a PaginatedList query rather than a simple array.

Example

@Relations({ entity: Collection, omit: ['productVariant'] }) relations: RelationPaths<Collection>,