[RFC] exporting variables between queries

[bbakerman]

RFC exporting variables between queries

This RFC calls for the ability to "export" variables from one query into another.

This allows a single server call to be made and outputs from one query to be fed into
others as variables.

So given:

query A {
    hero 
    {
        id @export(as:"droidId")
        name 
        friends  @export(as:"r2d2Friends") 
        {
            name @export(as:"friendNames")
        }
    }
}
        
query B($droidId : String!) {
    droid (id : $droidId ) {
        name
    }
}

Output values from operation A would be exported as the variables named "droidId", "r2d2Friends", and "friendNames"

The operation B would be detected to be dependent on operation A and would be executed after operation A completes. It would receive the
value of "droidId" as a variable from operation A

Multiple operation support

This RFC is dependent on #375, that is the ability to execute multiple operations in one server interaction

Variable arity

There are design questions around variable arity. In the example above the "droidId" exported variable can be thought of as a singleton value because the surrounding types are not lists types.

Where as "r2d2Friends" can be thought of as a list value because the surrounding types are list values and hence multiple exported variable values are possible.

One can imagine in certain cases some one might want map like semantics so that "the first / last" value of a list is considered a singleton value.

Naming could be used to indicate behaviour say, for example where plural export names imply a list while singlar variable names imply a singleton value. eg: "droidId" would always be considered a singleton value where as "friendNames" would always be considered a list value.

This is a great discussion point we think.

Consumer Supplied Variable Values

If the consumer caller supplies their own variable values, these will be passed to each operation. The exported variables will be placed into the variables map and will overwrite any existing variables with the same name key.

Exported Variable Value Validation

Validation of the variable values would follow the same rules as consumer supplied variable values.

Validation errors would be placed on each operation execution result

Current implementations

Sangria has this capability today https://sangria-graphql.org/learn/#batch-executor and graphql-java has a PR exploring the idea graphql-java/graphql-java#808

These are based on the ideas presented in a Facebook presentation about capabilities used within Facebook today.

We would love to see the Facebook learnings represented back out to the greater graphql community.

[OlegIlyenko]

Thanks a lot for starting this discussion, @bbakerman! These are very good discussion points.

In my current implementation, I took a quite pragmatic approach. I realize that the decisions that I took might be suboptimal. So, the feature is marked as experimental ATM and my hope is to change semantics as soon as better options emerge:

• Variable arity: For all @exports with the same name I merge the values in a list. When it comes time to give a value to the target query, I'm trying to adjust it to the type of the variable. So, for instance, if the exported variable is of type [Person] and query requires Person!, I will take the first element of the list.
• Consumer Supplied Variable Values: if a name of the variable is the same (in @export and in user-supplied variable), I decided to merge them into a list and then make the same adjustments as described above
• Exported Variable Value Validation: I rely on the standard execution mechanism. Every query executed in isolation and all variable-related errors are handled in the same way as during the normal query execution (so some query results might have something in errors array).

I also would like to add some point that I found quite interesting as I was working on it. In the following query:

query q1 {
  person(id: 1) {
    email @export(as: "emails") 
  }
}

query q2 {
  person(id: 2) {
    email  @export(as: "emails") 
  }
}
           
mutation SendEmails {
  notify(emails: $emails, message: "🍪 Free cookies! 🍪")
}

There are several things to consider and define semantics for:

• $emails is exported twice. Should something like this be allowed? ATM I do allow it and merge variable values in a list. When it comes time to execute the SendEmails mutation, I will adjust the value of the variable, if necessary (according to the variable type)
• Variable inference - in the presentation, I haven't seen any explicit variable declarations. So I assumed that some kind of type inference takes place. I have implemented the variable type inference in the current version, though it is:
  • strict - if the variable is used in multiple places, the type should match exactly. Inference takes place only if no explicit definition is present and the variable with the same name is exported somewhere.
  • optional - it is possible to completely disable it. In this case, variables must be always be defined explicitly
• Variables are exported from 2 queries and used in the 3rd mutation. I wonder what you think about this pattern and whether it should be allowed. (I do allow it ATM)

@leebyron In your presentation you haven't touched on the implementation details. At this point, it would be very interesting to learn how you defined the discussed semantics in your implementation. It would be great if you could share this and your thoughts on these points :)

[rmosolgo]

Wow, I never noticed that in the presentation, there were no explicit variable declarations (from the link above):

I wonder if this could be simpler if we used declarations in both cases, for example:

query NewsFeed($ids: [ID!]) {
  feed {
    stories {
      id @export(as: $ids)
    }
  }
}

query StoryComments($ids: [ID!]) {
  stories(ids: $ids) { 
    # ...
  }
}

In that way, both operations are already syntactically valid and we remove the need for maybe-ambiguous type inference.

But, are there shortcomings to that approach?

[alexgenco]

Just wanted to revive this conversation, as it would be a huge win for my team right now.

Would it be helpful to make the @export directive be explicit about whether the exported variable is a list or not? For instance, @export(as: "id") would export a single variable $id and throw an exception if it is declared again, and @export(into: "ids") would allow multiple declarations (or a single declaration inside a list type), and just shovel successive results into the list.

[alexgenco]

Another thought: My team's current requirements could probably be satisfied in a single operation with multiple mutations inside it, rather than multiple operations. This could potentially simplify the export variable type declarations, which could go in a directive next to the normal declared variables of the operation. Something like:

mutation CreateAndFollowUser($input: UserInput!) @exported($userId: String) {
  createUser(input: $input) {
    user {
      id @export(as: "userId")
    }  
  }

  followUser(userId: $userId) {
    success
  }
}

Here are a couple limitations right off the bat:

• This potentially adds overhead since the second mutation has to wait for the first to complete before executing.
• This doesn't allow passing variables across queries/mutations/subscriptions.

I think the first limitation could be remedied by using @defer. For instance, the query could change to

  followUser(userId: $userId) @defer {
    ...
  }

And then the followUser response could stream out after the createUser response.

I'm not sure I have a remedy for the second limitation yet, but maybe we could punt on that until multiple operation support makes it to spec? 🤷‍♂️

[cmonty]

I like the concept of the @export directive. One question that comes to mind, though: the examples within this issue all deal with simple variable passing, meaning not complex input types. @alexgenco, correct me if I'm wrong, most of the mutations we deal with only take complex input objects.

input ChargePaymentMethodInput {
  clientMutationId: String
  paymentMethodId: ID!
  transaction: TransactionInput!
}

mutation TokenizeAndChargePaymentMethod($tokenizeInput: TokenizeCreditCardInput!, $chargeInput: ChargePaymentMethodInput!) {
  tokenizeCreditCard(input: $tokenizeInput) {
    paymentMethod {
      id @export("paymentMethodId")
    }
   }
   chargePaymentMethod(input: $chargeInput) {
     transaction {
       id
       status
     }
   }
}

How were you thinking of passing the exported paymentMethodId variable to ChargePaymentMethodInput?

[mathstuf]

@export(into: "ids") would allow multiple declarations (or a single declaration inside a list type), and just shovel successive results into the list.

Not sure how the syntax would work, but #517 deals with running a given query with a list of input parameters.

[alexgenco]

@cmonty I think you basically have to inline all inputs down to the level of the exported variable, but anything deeper you could still include as an operation variable. So your example would be:

mutation TokenizeAndChargePaymentMethod(
  $tokenizeInput: TokenizeCreditCardInput!,
  $transactionInput: TransactionInput!
) @exported($paymentMethodId: String) {
  tokenizeCreditCard(input: $tokenizeInput) {
    paymentMethod {
      id @export(as: "paymentMethodId")
    }
  }
  chargePaymentMethod(input: {
    paymentMethodId: $paymentMethodId,
    transaction: $transactionInput
  }) {
    transaction {
      id
      status
    }
  }
}