Mapping Language

This reference describes the Apollo Connectors mapping language. You use the mapping language anywhere data needs to be transformed from one form to another. This includes building URIs and headers, constructing request bodies when making requests, and mapping response data to GraphQL schema.

The basics

The mapping language uses a declarative approach to transforming data from one shape to another. Unlike traditional programming languages, it doesn't have state or loops. Since the mapping language borrows heavily from the GraphQL query language, some concepts like the alias syntax and array handling might look familiar.

Fields and paths

The most basic mapping expression selects a value from a path. For example, a URI path might include the expression $args.id. This expression means, "Use the id field of the $args variable." For example:

type Query {
  product(id: ID!): Product
    @connect(
      source: "ecomm"
      http: { GET: "/products/{$args.id}" }
      selection: "id name description"
    )
}

When applied to an array, the result of a path is also an array. For example, if $args.filters is an array of objects, $args.filters.value is an array of the value property of each object.

{
  "filters": [
    { "value": 1 },
    { "value": 2 },
    { "value": 3 }
  ]
}

[1, 2, 3]

Creating objects

For this section, assume that $args contains this JSON object:

{ "handle": "alice", "email": "alice@example.com" }

When you give a value a name, you create an object containing that value:

username: $args.handle

{ "username": "alice" }

You can combine multiple fields to create an object with multiple properties:

username: $args.handle
email: $args.email

{
  "username": "alice",
  "email": "alice@example.com"
}

Nested objects

You can create a new object as the property of another object using curly braces ({}):

user: {
  username: $args.handle
  email: $args.email
}

{
  "user": {
    "username": "alice",
    "email": "alice@example.com"
  }
}

Subselections

If multiple properties from an object come from another object, you can use a subselection to avoid repeating the object name. The $ variable in the curly braces refers to the selected object—whatever comes directly before the {. In the following example, that's $args.

$args {
  username: $.handle
  email: $.email
}

{
  "username": "alice",
  "email": "alice@example.com"
}

As shorthand, you can omit $. and refer to the fields only by their names:

$args {
  username: $.handle
  email: $.email
}

$args {
  username: handle
  email: email
}

When the name of the new field matches the name of the source, you can also omit the left-hand side:

$args {
  username: handle
  email: email
}

$args {
  username: handle
  email
}

You can combine this with the ability to create nested objects by adding back in the user: field name:

user: $args {
  username: handle
  email
}

{
  "user": {
    "username": "alice",
    "email": "alice@example.com"
  }
}

Multiple levels

For more complex inputs, you can use multiple subselections to achieve the desired result without repetition. Suppose $args looks like this:

{
  "user": {
    "handle": "alice",
    "email": "alice@example.com"
  },
  "company": {
    "name": "Acme",
    "address": "123 Main St"
  }
}

You can select all the data like this:

$args {
  user {
    username: handle
    email
  }
  organization: company {
    name
    address
  }
}

{
  "user": {
    "username": "alice",
    "email": "alice@example.com"
  },
  "organization": {
    "name": "Acme",
    "address": "123 Main St"
  }
}

Special case for selection

For the @connect directive's selection argument only, a top-level $ refers to the root of the response body from the source API. This means you can select basic GraphQL fields succinctly.

For example, given this JSON response:

{
  "id": "1",
  "username": "alice",
  "email": "alice@example.com"
}

You can use this basic selection to select all of a user's fields.

type Query {
  user(id: ID!): User
    @connect(
      http: { GET: "https://api.example.com/users/{$args.id}" }
      selection: "id username email"
    )
}

type User {
  id: ID!
  username: String!
  email: String!
}

Since the REST endpoint returns username and email in its response, you can map them directly to fields of the same name in the GraphQL schema using the shorthand that omits the $.

Variables

Variables are the sources of data to be transformed. Variables can refer to:

• GraphQL arguments

• sibling fields

• request and response data

• information from the router

The available variables depend on the context of the expression.

Additional variable notes

$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.

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.

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

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.

$

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.

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

@

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.

Literal values

You can use literal values with $(). This is useful for adding constant values to the request body.

body: """
hello: $("world")
theAnswer: $(42)
isTrue: $(true)
anObject: $({ key: "value" })
aList: $([1, 2, 3])
"""

To avoid using the $() wrapper repeatedly, you can wrap an entire object with $():

body: """
$({
  hello: "world",
  theAnswer: 42,
  isTrue: true,
  anObject: { key: "value" },
  aList: [1, 2, 3],
})
"""

Inside the $()expression, you can use any JSON literal: numbers, strings, booleans, arrays, objects, and null.

Variables in literals

You can use variables, like $args and $this, in literal values.

selection: """
names: $([             # a list field like `names: [String]`
  $args.input.name,    # a variable
  results->first.name  # a selection
])
"""

Given the following inputs for the example above:

{
  "$args": {
    "input": {
      "name": "Alice"
    }
  }
}

{
  "results": [
    { "name": "Bob" }
    { "name": "Charlie" }
  ]
}

The selection mapping results to:

{ "names": ["Alice", "Bob"] }

Using literals in with @connect

Currently, the following rules apply when using literal values with the @connect directive:

1. All literal values in the body argument are always allowed.

2. Scalar literal values (strings, numbers, booleans) and lists of scalars are allowed in the selection argument.

3. Literal values can't be mapped to a field that returns a nested object or list of nested objects.

4. Literal objects and lists and lists of objects are allowed only if they're mapped to a custom scalar field.

See corresponding examples of these rules below. The number in parentheses, for example, (1) on line 6 shows an example of rule 1.

1type Mutation {
2  createPost(input: CreatePostInput!): PostPayload
3    @connect(
4      http: {
5        POST: "https://api.example.com/posts"
6        body: """
7        $({ id: 1, title: "Hello, world!" }) # ✅ (1)
8        """
9      }
10      selection: """
11      success: $(true) # ✅ (2)
12      post: $({ id: 1, title: "Hello, world!" }) # ❌ (3)
13      metadata: $({ key: "value" }) # ✅ (4)
14      """
15    )
16}
17
18type PostPayload {
19  success: Boolean
20  post: Post # ⚠️ Object type
21  metadata: JSON
22}
23
24scalar JSON

Methods

You can transform values using the ->method syntax.

The arguments passed to a method can be either JSON literals (numbers, strings, booleans, arrays, objects, and null) or the following variables: $, $args, $this, or $config.

The mapping language provides the following methods:

See the transforming values section of the response mapping guide for examples of common transformations.

Additional resources

• Refer to the guide on Mapping GraphQL Responses for examples of common selection mapping types and transformations.

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

• Enhance your developer experience by enabling IDE support for the mapping language, including syntax highlighting, validation, autocomplete, and more.