This section will explain how JOINs work, what specific requirements they have, and what the caveats are.
To achieve a cross-api JOIN, three things are required:
- you need a variable to store the JOIN key, this variable should be
- you need to use the
@exportdirective to export a single value into the JOIN key
- you have to use the
_joinfield to join an object type with another Query result
Let's look at an example to illustrate the flow.
Imagine we'd like to use two APIs to build an API that returns the current weather for all capitals of one of the continents in the world. To achieve this, we could use the following two APIs:
Using these two APIs, we're ready to configure the JOIN:
WunderGraph executes GraphQL Documents depth-first. This means that you can only access the JOIN key when the export happened before the _join field. In our example, the field
capital is exported before the
_join field, so we can access the JOIN key.
Additionally, it's not possible to use the exported variable from within the same "scope". A scope is the tree of neighbouring fields that query data from the same DataSource. You can use the
_join field to create a new scope. Just make sure that your JOIN key is evaluated before the execution of the _join field, in depth-first order.