Skip to content

#427 - NullValue support plus "provided null" versus "not provided" null values - #434

Closed
bbakerman wants to merge 3 commits into
graphql-java:masterfrom
bbakerman:427-null-value-support
Closed

bbakerman wants to merge 3 commits into
graphql-java:masterfrom
bbakerman:427-null-value-support

Conversation

@bbakerman

Copy link
Copy Markdown
Member

This is an early push for demostration purposes

… provided" null support

This is an early push for demostration purposes
@bbakerman
bbakerman requested a review from andimarek May 13, 2017 10:00
@andimarek

andimarek commented May 13, 2017 •

Copy link
Copy Markdown
Member

The current behaviour is as following:

type query {
  foo (bar: String): String
  foo2 (bar: ComplexInput): String
}
input ComplexInput {
  complexKey: String
}
  1. Query foo(bar: "test") -> Arguments Map contains key "bar" with value "test".

  2. Query foo -> Arguments Map contains key "bar" with value null.

  3. Query foo2 -> Arguments Map contains key "bar" with value null.

  4. Query foo2(bar: {}) -> Arguments Map contains key "bar" with value empty Map.

  5. Query foo2(bar: {complexKey: "complexValue"}) -> Arguments Map contains key "bar" with value a Map "complexKey" -> "complexValue"`.

The important aspect here ist that there is a difference between a "first level argument" (bar at foo), which is never "not there" and a key for a InputObject (complexKey at ComplexInput), which can be completely missing.

Null values:

When we allow explicit null values (foor(bar: null) or foo2(bar: {complexKey: null}) we must provide a way to distinguish it from other cases.

While it may enough for InputObject to transform null queries into a Map with "complexKey" -> null (Java null) this is not enough for direct arguments: e.g. foo can't be distinguished from foo(bar: null) (both result in "foo" -> null)

It is important to note that we should not change the current behaviour: changing it would be a very subtle runtime change, which would probably lead to bugs.

### Suggestion: Explicit Null Value (See #434 (comment) for the solution)
I think the best solution without breaking anything is to add a GraphQLNull Value class, similar to this:

class GraphQLNullValue {
  private static final NULL = new GraphQLNullValue();
  private GraphQLNullValue() {
  }
}

This would result in:

  1. Query foo(bar: null) -> Arguments Map contains key "bar" with value GraphQLNullValue.NULL.
  2. Query foo2(bar: {complexKey: null}) -> Arguments Map contains a key "bar" with a Map "complexKey:" -> GraphQLNullValue.NULL

This way we would have a consistent way how we treat null arguments and it would be very explicit.

But: While this would be consistent and explicit, it would be a breaking change: suddenly there could be another value in the arguments Map, which is not of the expected type.

I think we must make it optional (and turned off by default), if someone really wants to distinguish between null and not provided.

Update: See #434 (comment) for the solution

@kaqqao

kaqqao commented May 13, 2017

Copy link
Copy Markdown
Contributor

@andimarek Even though I find this approach more cumbersome to use (requires checking for this special value in addition to checking for nulls), I think it is the correct approach. It's very explicit and unambiguous, and that is IMHO the most important metric for a low-level library.

@andimarek

Copy link
Copy Markdown
Member

@kaqqao yes,

I am also not totally happy with it, because if you allow null values, now you have to check for an additional type (is it == GraphQLNullValue.NULL).

Which is a breaking change, when I think about it: If someone upgrades graphql-java and allows null values, suddenly there can be a new value in the arguments Map, which can't be cast to the expected value (e.g. String or boolean).
🤔 Not sure this is good.

@bbakerman

Copy link
Copy Markdown
Member Author

BTW we can split this PR into 2 - the ability to specifynull as a literal value and the "absence of null" at runtime.

The first has some value just in being able to do literal specifications

The absence of null is valuable for the mutation reasons

@bbakerman

Copy link
Copy Markdown
Member Author

When I started this PR I first had the idea of a special sentinal value eg: GraphQLNullValue.NULL

But while explicit, its really Java unnatural. Its easier in javaScript since they have 'undefined' and 'null' values for this use case (sort of).

I was thinking about it from the consumers point of view and thats the DataFetcher

        Object get(DataFetchingEnvironment environment) {
               Map<String,Object> args = environment.getArguments()
               Map<String,Object> argObject = arg.get("ComplexThing");
               
         }

The complex object is going to be a Map and hence trying to work out if "bar" is present or not can be done via argObject.contains("subFIeld")

 if (argObject.contains("subField") {
      updateSubField(argObject.get("subField"))

The proposed code would then be more like

 Object subValue  = argObject.get("subField");
 if (! GraphQLNullValue.NULL.equals(subValue))
      updateWithSubField(subValue)

It just feels a lot less expected. Its precise but its less natural.

Either way the change is a behaviour breaking change since existing code cant know that GraphQLNullValue.NULL is possible or that null handling has changed.

@andimarek

Copy link
Copy Markdown
Member

@bbakerman I agree that it would be unnatural and in case of a complex InputObject your idea feels nice, but what about foo vs foo(bar: null) (my example from above)? How do you handle that?

@andimarek

Copy link
Copy Markdown
Member

and btw: I would prefer not to add that topic to 3.0.0 ... it is already a lot. We should aim for 4.0.0 for that change.

@andimarek

andimarek commented May 14, 2017 •

Copy link
Copy Markdown
Member

just so that we don't forget to think about that case:

this change also allows null in lists: This is a valid query:

someField(value: ["Value1", null, "Value3"])

@andimarek andimarek added this to the 4.0.0 milestone May 14, 2017
@kaqqao

kaqqao commented May 14, 2017 •

Copy link
Copy Markdown
Contributor

@andimarek I don't think I'm getting you about foo vs foo(bar: null). foo here is a query name and bar an optional argument, right? In that case, won't one result in an empty argument map, and the other in a map with key bar and value null?

@andimarek

Copy link
Copy Markdown
Member

@kaqqao that is exactly the problem: It won't:

foo results in an argument map with "bar"-> null. This is the current behaviour: bar is never missing

As you can see there is no way to differentiate between foo and foo(bar: null): Under the constraint that we do not wan't to change the current behaviour both would result in "foo" -> null.

@bbakerman bbakerman added the breaking change requires a new major version to be relased label May 15, 2017
@bbakerman

Copy link
Copy Markdown
Member Author

Have a look at : https://github.com/facebook/graphql/blob/master/spec/Section%203%20--%20Type%20System.md

And the Input Coercion part of it :

For each field of the input object type, if the original value has an entry with the same name, and the value at that entry is a literal value or a variable which was provided a runtime value, an entry is added to the result with the name of the field.

The value of that entry in the result is the outcome of input coercing the original entry value according to the input coercion rules of the type declared by the input field.

Following are examples of Input Object coercion for the type:

input ExampleInputObject {
  a: String
  b: Int!
}
Original Value	          Variables	Coerced Value
{ a: "abc", b: 123 }   {null}	        { a: "abc", b: 123 }
{ a: 123, b: "123" }	 {null}	        { a: "123", b: 123 }
{ a: "abc" }	         {null}	        Error: Missing required field {b}
{ a: "abc", b: null }	 {null}	        Error: {b} must be non-null.
{ a: null, b: 1 }	         {null}	        { a: null, b: 1 }
{ b: $var }	         { var: 123 }	{ b: 123 }
{ b: $var }	         {}	                Error: Missing required field {b}.
{ b: $var }	         { var: null }	Error: {b} must be non-null.
{ a: $var, b: 1 }	 { var: null }	{ a: null, b: 1 }
{ a: $var, b: 1 }	 {}	                { b: 1 }

Note: there is a semantic difference between the input value explicitly declaring an input field's value as the value {null} vs having not declared the input field at all.

So I think for 4.0 it would be right thing to do to move towards "spec" and use the absence of the field in the map to indicate that absence and presence in the map (with possible null value) to indicate present with some value (which maybe null or not)

Using a sentinel GraphqlNullValue is a mistake I think. Saving this change for 4.0 say because of the breaking runtime behavior

@bbakerman

Copy link
Copy Markdown
Member Author

BTW - there is minor runtime breaking behaviour in adding 'null literal' support

Technically foo(arg : null) will today be parsed as a enum and hence we when add the null keyword support that will no longer work./

I think this is really minor since it would require some one to be accepting a enum and the word null being one of the enum values. I think we can ignore that as being bad

@andimarek

andimarek commented May 15, 2017 •

Copy link
Copy Markdown
Member

After talking with @bbakerman we came to the following solution:

It is the best for the future to map "not provided" to "no key in map" and null to a java map with a key and java null as value. This is very straight forward and intuitive.

But:
As mentioned before it breaks the current behaviour for foo (see my example above): After that change there would be no "bar" key in the arguments map.

Legacy Option:
This is a very subtle change and it might break stuff. To adress that we will add a legacy arguments option in 4.0.0: this flag keeps the current behaviour and results in the same arguments map for foo and foo(bar: null).

This option will be removed in version 5.

The special Enum case (#434 (comment)) will just be documented.

@kaqqao

kaqqao commented May 15, 2017

Copy link
Copy Markdown
Contributor

While the missing key vs the current key-with-null is indeed a subtle change, I don't think it's likely to cause any damage. Currently the key is always present so there's really no reason anyone would be checking for its presence (the part that is changing), and args.get(missingKey) returns null anyway.

@andimarek

andimarek commented May 15, 2017 •

Copy link
Copy Markdown
Member

@kaqqao I agree it is a very subtle change. But especially with these changes we try to be empathic with our users.

@andimarek

andimarek commented May 21, 2017 •

Copy link
Copy Markdown
Member

These tests document the current behaviour: d8bfa00

The first test (d8bfa00#diff-3eca2508c3f86d5d839beca2e0e520faR360) would break with the introduction of null values.

The more I think about, the more I am convinced that we don't need a legacy option flag: it is a very subtle change, but I believe it would not really break anything. (

To break something the code would need to relay on the existing of a key in a map being null.
But the following would be still okay:

if (arguments.get("bar") != null) ...

for a query {foo}. @bbakerman

@kaqqao

kaqqao commented May 21, 2017 •

Copy link
Copy Markdown
Contributor

This was exactly my point in the previous message. Unless the code does arguments.contains("key"), it will be fine. And there's currently no reason to ever check contains as it is always true... So the change is highly unlikely to cause any damage.

@andimarek

Copy link
Copy Markdown
Member

@kaqqao Yes, you right. Didn't want to neglect your comment ... just needed some time let that sink in.

@bbakerman

Copy link
Copy Markdown
Member Author

Damn I have buggered this branch right up. I am going to throw it away and start again...with a TDD approach.

And I have the right PR this time

@bbakerman bbakerman closed this May 22, 2017
@bbakerman

Copy link
Copy Markdown
Member Author

And now I see that tests have already been added.... missed that sorry.

Anyway I am starting a new branch either way to make sure I am 3.0 clean

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking change requires a new major version to be relased

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants