Mapping Variable Reference

Access and transform data using variables

tip
Check out the Connectors Mapping Playground to experiment with and troubleshoot mapping expressions.

Variables are the building blocks for transforming data in GraphOS Connectors. They provide access to the various data sources that can be used in your mapping expressions, allowing you to dynamically connect your GraphQL schema to your REST APIs.

Variables can refer to:

  • GraphQL arguments

  • sibling fields from parent objects

  • request and response data

  • information from the router

Available variables

The available variables depend on the context of the expression.

Variable Definition Availability Notes

$

At the top level, $ refers to the root of the API response body.
Within a {...} sub-selection, $ refers to the value of the parent. See an example.
  • Only available on non-root types, that is, not within Query or Mutation Connectors.
  • Not available in @source.

$args

The arguments passed to the field in the GraphQL query. For a field defined like product(id: ID!): Product, $args.id refers to the id argument passed to the product field.
  • Available in any expression in a @connect directive if arguments are defined for the field.
  • Not available in @source.

$config

Variables set in the GraphOS Router configuration. Always available.

$context

Context set by router customizations like coprocessors.Only available if router customizations exist where context has been set.

$status

The numeric HTTP status code (200, 404, etc.) from the response of the connected HTTP endpoint.Only available in @connect's selection mapping.

$this

The parent object of the current field. Can be used to access sibling fields. Learn about dependencies $this can create.
  • Only available on non-root types, that is, not within Query or Mutation Connectors.
  • Not available in @source.

@

The value being transformed with a method. Behaves differently depending on the context. Learn more. Depends on the specific transformation method or mapping being applied.

Additional variable notes

$

When used at the top-level of an expression, $ is only valid within the selection field of a Connector, and refers to the root of the response body from the API. When used within a {...} sub-selection, $ refers to the value of the parent.

connectors
$.results {  # Here `$` refers to the response body
  id: $.id  # `$` refers to the `results` field
}

$this

Using $this creates a dependency between the Connector and fields on the parent object. This implies that another Connector or another subgraph can provide this field.

GraphQL
type Product {
  id: ID!
  reviews: [Review]
    # Some other Connector or subgraph provides the `id` value.
    @connect(http: { GET: "/products/{$this.id}/reviews" }, selection: "id rating comment")
}

This feature of $this is equivalent to the @requires directive in Apollo Federation.

For example, the following Connectors usage is equivalent to the following @requires usage in a subgraph schema.

GraphQL
type Product {
  id: ID!
  weight: Int
  shippingCost: Int @connect(http: { GET: "/shipping?weight=${this.weight}" }, selection: "$")
}
GraphQL
type Product @key(fields: "id") {
  id: ID!
  weight: Int @external
  shippingCost: Int @requires(fields: "weight")
}

In fact, you can combine Connectors with @requires to create computed fields using REST APIs.

@

Refers to the value being transformed with a method, which is sometimes the same as $, but not always.

For example, in the value->echo({ wrapped: @ }) example in the methods section, @ refers to the value of value, while $ refers to the object containing value.

Additionally, in the colors->map({ name: @ }) example, the method binds @ to each element in the $.colors list, while $ remains unchanged.