mirror of https://github.com/hasura/graphql-engine.git synced 2024-12-15 17:31:56 +03:00

Antoine Leblanc 6e1761f8f9 Enable remote joins from remote schemas in the execution engine.

### Description

This PR adds the ability to perform remote joins from remote schemas in the engine. To do so, we alter the definition of an `ExecutionStep` targeting a remote schema: the `ExecStepRemote` constructor now expects a `Maybe RemoteJoins`. This new argument is used when processing the execution step, in the transport layer (either `Transport.HTTP` or `Transport.WebSocket`).

For this `Maybe RemoteJoins` to be extracted from a parsed query, this PR also extends the `Execute.RemoteJoin.Collect` module, to implement "collection" from a selection set. Not only do those new functions extract the remote joins, but they also apply all necessary transformations to the selection sets (such as inserting the necessary "phantom" fields used as join keys).

Finally in `Execute.RemoteJoin.Join`, we make two changes. First, we now always look for nested remote joins, regardless of whether the join we just performed went to a source or a remote schema; and second we adapt our join tree logic according to the special cases that were added to deal with remote server edge cases.

Additionally, this PR refactors / cleans / documents `Execute.RemoteJoin.RemoteServer`. This is not required as part of this change and could be moved to a separate PR if needed (a similar cleanup of `Join` is done independently in #3894). It also introduces a draft of a new documentation page for this project, that will be refined in the release PR that ships the feature (either #3069 or a copy of it).

While this PR extends the engine, it doesn't plug such relationships in the schema, meaning that, as of this PR, the new code paths in `Join` are technically unreachable. Adding the corresponding schema code and, ultimately, enabling the metadata API will be done in subsequent PRs.

### Keeping track of concrete type names

The main change this PR makes to the existing `Join` code is to handle a new reserved field we sometimes use when targeting remote servers: the `__hasura_internal_typename` field. In short, a GraphQL selection set can sometimes "branch" based on the concrete "runtime type" of the object on which the selection happens:

```graphql
query {
author(id: 53478) {
... on Writer {
name
articles {
title
}
}
... on Artist {
name
articles {
title
}
}
}
}
```

If both of those `articles` are remote joins, we need to be able, when we get the answer, to differentiate between the two different cases. We do this by asking for `__typename`, to be able to decide if we're in the `Writer` or the `Artist` branch of the query.

To avoid further processing / customization of results, we only insert this `__hasura_internal_typename: __typename` field in the query in the case of unions of interfaces AND if we have the guarantee that we will processing the request as part of the remote joins "folding": that is, if there's any remote join in this branch in the tree. Otherwise, we don't insert the field, and we leave that part of the response untouched.

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/3810
GitOrigin-RevId: 89aaf16274d68e26ad3730b80c2d2fdc2896b96c

2022-03-09 03:18:22 +00:00

1.8 KiB

Raw Blame History

Server engineering documentation

This page documents the structure and the internal architecture of the GraphQL Engine Server. To get started, you can read the overview. We also maintain a glossary of all the terms we use throughout the code and the documentation.

You can also get started with a list of tips and tricks.

Haddock documentation

You can browse the generated haddock documentation for the engine's code; we automatically update it on every push to a branch of interest:

Architecture deep-dive

how to understand our GraphQL schema
how to perform database migrations
how the execution of remote joins works

TODO: we can either list individual topics here, or point to architecture/ and have a README file there.

Notes

In our Haskell codebase, we use GHC-style notes for long-form comments detailing a specific aspect of the codebase. We gather all of them, as of the main branch, in the notes subfolder.

Updating this documentation

All markdown files in this folder are either copied verbatim from server/documentation or generated as part of our CI; do not open a PR to modify files in the gh-pages branch, and instead modify their source directly. Notes are extracted using the scripts/extract-nodes bash script. The haddock documentation is generated by running cabal haddock --haddock-internal --haddock-options="--ignore-all-exports".

1.8 KiB Raw Blame History