Documentation

A JoinTree represents the set of operations that need to be executed to enrich the response of a source with data from remote sources. A tree structure is used to capture the locations in the response where the join has to happpen as it offers an efficient traversal mechanism.

For a query such as this:

{ city { name code # weather is a remote relationship weather { forecast } state { # weather is a remote relationship weather { forecast } } } }

the join tree would look like [ , ("weather", Leaf RemoteJoinInfoOfWeather), , ("state", [ ("weather", Leaf RemoteJoinInfoOfWeather) ]) ]

Note that the same join tree will be emitted even if city is of type '[City]' and state is of type [State], we currently do not capture any information if any of the fields in the path expect json arrays. It is similar in spirit to a GraphQL selection set in this regard.

This structure is somewhat similar to a prefix tree such as Trie, but has two additional guarantees: - a JoinTree is never empty, - there cannot exist a pair of values for which one's prefix key is a subset of the other: every value is effectively a leaf.

A field name annotated with an optional type name.

To deal with ambiguous join paths, such as those that emerge from GraphQL interfaces or GraphQL unions, we do not just keep track of the fields' name, but also, optionally, of their type. Whenever a selection set is deemed ambiguous, we insert a reserved field in the query to retrieve the typename, __hasura_internal_typename; when traversing the join tree, if that key is present, then we use it alongside the field name when querying the join tree (see traverseObject in the Join module).

We use Text for the representation of the field name instead of FieldName, for simplicity: the join tree is only meant to be queried using the values we get in the reponse, which will be unrestricted text.

Each leaf associates a mapping from typename to actual join info. This allows to disambiguate between different remote joins with the same name in a given selection set, which might happen with union or interface fragments.

Collect all the remote joins to a remote schema from a join tree.

An individual join entry point in a JoinTree.

Either a join against a source, or against a remote schema. In either case, the constructor will contain that particular join's information (a RemoteSourceJoin or RemoteSchemaJoin respectively) and, recursively, the set of follow-up RemoteJoins from that target, if any.

A unique id that gets assigned to each RemoteJoin (this is to avoid the requirement of Ord/Hashable implementation for RemoteJoin)

Disambiguates between FieldNames which are provided as part of the GraphQL selection provided by the user (i.e. JCSelected) and those which we need to retreive data but which are not expressly requested (i.e. JCPhantom).

After processing the remote join, we remove all phantom FieldNames and only return those which fall under the JCSelected branch of this type.

Extracts the field name from the JoinColumnAlias, regardless of whether the field is requested by the user of a "phantom" field.

Extracts the list of phantom field names out of a given RemoteJoin, i.e. the name of the fields that must be part of the query but were not requested by the user.

Extracts an abstracted field mapping for a particular RemoteJoin, using a common representation.

The RHS of the mapping uses JoinColumnAlias instead of FieldName to differentiate between selected fields and phantom fields (see JoinColumnAlias).

A RemoteSourceJoin contains all the contextual information required for the execution of a join against a source, translated from the IR's representation of a selection (see AnnFieldG).

A RemoteSchemaJoin contains all the contextual information required for the execution of a join against a remote schema, translated from the IR's representation of a selection (see AnnFieldG).

A map of fieldname to values extracted from each LHS row/object

For example, if a remote relationship weather on city table is defined as follows: city.weather = get_weather(city: city.code, cityState: city.state_code) a join argument for this join would have the values of columns code and state_code for each city row that participates in the join

A unique id assigned to each join argument