directive @materializer

A shorthand syntax is supported for fields, where a field has a leaf type instead of an input object containing predicate opcodes.

Supported shorthand types are:

• String, ID, Boolean - Equality, equivalent to an input object of {eq: T} where T is the field type.

• Enum types - Equality, equivalent to an input object of {eq: E} where E is the field enum type.

Example: EmployeeFilter supports ID for manager.

The arguments argument provides argument mapping for the materializer field set (query). It provides values for the materializer field set from the following sources:

• fields in the enclosing type, for example: {name:"id" field:"author_id"}

• arguments of the field being materialized, for example: {name:"unit" argument:"unit"}

• constants, for example {name: "closed" const: false}

The query argument specifies:

• a field set selection that resolves the annotated field (location FIELD_DEFINITION);

• a selection set with type conditions that indicate how source types are reshaped into the annotated type (location OBJECT).

With GraphQL, you model your business domain as a graph.

The @materializer custom directive allows you to add relationships into your schema's graphql by adding fields to types.

This example shows how @materializer adds to a customer object type to include their orders from a different backend system.

When Customer.orders is selected, it will be resolved by Query.orders.

In this case argument mapping is implicit, with @materializer the argument Query.orders(id:) defaults to a field of the same name and type in the enclosing type (Customer).

type Query {
  customer(id: ID!): Customer @dbquery(type: "postgresql", table: "customers")
  orders(id: ID!): [Order]
    @graphql(endpoint: "$url", configuration: "orders-system")
}

type Customer {
  id: ID!
  name: String
  email: String

  orders: [Order] @materializer(query: "orders")
}

Now a request can be made such as:

query Customer($id: ID!) {
  customer(id: $id) {
    name
    email
    orders {
      id
      cost
      delivered
    }
  }
}

In this case, the single GraphQL incoming request will result in two outgoing requests, to the database and backend GraphQL systems, but the client making the original GraphQL request is unaware of how the response is created.

Note that the materializing field Query.orders can be resolved by any means, including @connector, @dbquery, @documentstore, @graphql, @materializer, @rest, @sequence and @value, or field that is resolved through @supplies.

A typical pattern is not to add fields to the original type (Customer) definition, but instead use extend type.

This would leave the original Customer defintions as:

type Customer {
  id: ID!
  name: String
  email: String
}

and separately extend it:

extend type Customer {
  orders: [Order] @materializer(query: "orders")
}

This separation:

• Works when the original definition cannot be modified (for example, pulled from a separate code repository).

• Allows deployment of endpoints with different combination of extensions (or none).

  • For example, endpoints with:

    • just customer information

    • customer and orders

    • customer and loyalty program information

  • Allows unit testing of schema elements.

• Allows source code locality for an extension and its related schema elements.

The directive argument @materializer(arguments:) allows mapping to field arguments of the materializing field from:

• fields of the enclosing type of the materialized field

• field arguments of the materializing field

• constants

Any required argument of the materializing field, must be set by @materializer, either through implicit or explicit (@materializer(arguments:)) mapping.

@materializer can be used with fields in the root operation type Query, one use is simple renaming of fields.

You may want to rename a field name or argument name when an existing name is unclear or does not match your naming convention.

Here Query.customerOrders effectively acts as a renaming of Query.orders_for_customer.

type Query {
  orders_for_customer(id: ID!): [Order]
    @dbquery(type: "postgresql", table: "orders")

  customerOrders(id: ID!): [Order] @materializer(query: "orders_for_customer")
}

When annotating fields in Query, field argments of the materializing field are mapped implicitly from arguments of the annotated (materialized) field. Explicit mapping is supported from arguments of the annotated field or constants.

To create a clean schema, materializing fields can be hidden through field visibility patterns using directive argument@sdl(visibility:), or by field access rules.

A common use for fields in Query is to create a field materialized by another field but constrain the arguments available to GraphQL requests.

For example, Query.openOrders is materialized by Query.orders but does not allow selecting all or just closed orders:

type Query {
  orders(id: ID!, open: Boolean = true): [Order]
    @dbquery(type: "postgresql", table: "orders")

  openOrders(id: ID!): [Order] @materializer(query: "orders_for_customer")
}

This example works because Query.orders(open:) is not required, argument mapping can be used with constants to provided values for required arguments or different values for optional arguments.

In this case, Query.orders would be hidden using field access rules or visibility.

With field access rules, accessible fields could be based upon a role in a JWT, so a customer could see all their orders through Query.orders, while a customer support representive could only see open orders through Query.openOrders.