Unlocking the Power of GraphQL: Exporting Values with Ease

The Need for @export

Imagine having to execute multiple queries just to retrieve a single piece of information. This is exactly what happens when you need to search for posts that mention the name of a logged-in user. You first need to retrieve the user’s name, and then pass it as a variable to perform the search. But what if you could combine these two queries into one, eliminating the need for the second query to wait for the first to execute?

This is where the @export directive comes in – a proposed feature that allows you to export the value of a field into a variable, making your queries more efficient and powerful.

How @export Works

The @export directive allows you to export:

• a single value from a single field
• a list of values from a single field
• a dictionary of values from the same object
• or even a list of dictionaries of values

This flexibility makes it an incredibly useful tool for simplifying your queries. For instance, you can use @export to:

• search for posts containing a specific keyword
• retrieve a list of friends’ names

query {
  user {
    name @export(as: "_username")
  }
  posts(search: "_username") {
    title
  }
}

Implementation Challenges

While the @export directive is a game-changer, its implementation is not without its challenges. One of the main issues is that GraphQL servers resolve fields in parallel using promises, making it difficult to control the order in which fields are resolved.

This means that the field exporting the value must be executed before the field reading the value. Fortunately, some GraphQL servers, such as Gato GraphQL, resolve fields sequentially, making it possible to implement @export.

Design Decisions and Gotchas

To make @export work, you need to follow a few peculiarities:

• The dynamic variable name must start with “_“
• You may need to use the self field to control the order in which fields are resolved
• The dynamic variable must be declared as a static variable in the operation name, with a default value

Dynamic @skip and @include

One of the most exciting applications of @export is making @skip and @include dynamic. Imagine being able to show or hide fields based on properties from the object itself, rather than external variables.

query {
  user {
    isAdmin @export(as: "_isAdmin")
  }
  posts(include: "_isAdmin") {
    title
  }
}

With @export, this is now possible.