[RFC] Flat chain syntax

[mnpenner]

Often times we want to fetch just a single field from a nested relation. e.g.

{
  clients(limit: 5) {
    id
    programs {
      shortName
    }
  }
}

It would be nice if there was a syntax to allow getting back a flat array of program shortNames instead of an array of objects. e.g.

{
  clients(limit: 5) {
    id
    programs: programs.shortName
  }
}

This would return something like:

{
  "data": {
    "clients": [
      {
        "id": 2,
        "programs": ["ABC","DEF"]
      },
      {
        "id": 3,
        "programs": ["ABC", "XYZ"]
        ]
      }
    ]
  }
}

Giving it an alias could either be mandatory, or it could default to using the outer field name (default to "programs", "shortName" would be discarded).

A library like GraphQL-JS could handle the normalization of array-of-objects to flat-array-of-strings automatically, so there wouldn't be any additional work for someone implementing a schema.

[geospofford-anaplan]

+1 The same would be convenient for getting a single field back from a non-list object field as well.

[benwilson512]

The downside here is that it's no longer definite what type a given key in the response has. programs in your case used to have a type that was a list of objects. Now it can be a list of objects OR a list of any field on that object.

[mnpenner]

@benwilson512 But I can already alias something else to programs and 'change its type' so to speak. Where would this be a problem? And if it is a problem, we could always go with the forced-alias solution, although I kind of do like the using the outer field name as the default.

Most of the places I would want to use this would be like client names, user names, program names, etc. in which case "clients", "users" and "programs" are already good defaults. I might also want to use it for lists of IDs, in which case I'd probably alias it to client_ids instead.

[mnpenner]

Another use-case would be to flatten Relay-style result sets for when you don't care about pagination.

e.g. instead of

{
  user {
    id
    name
    friends(first: 10, after: "opaqueCursor") {
      edges {
        cursor
        node {
          id
          name
        }
      }
      pageInfo {
        hasNextPage
      }
    }
  }
}

You would be able to do

{
    user {
        id
        name
        friends(first: 10).edges.node.name
    }
}

To get a user and his first 10 friends' names as a flat array, or

{
    user {
        id
        name
        friends.edges.node {
            id,
            name
        }
    }
}

To get an array of friend objects.

[rmosolgo]

-1 for adding syntax, something I love about GraphQL is that there isn't much to the syntax

[r4j4h]

I know referring to another library is kind of crappy, and this doesn't help with your symbolic extension, but would d3.nest help you reformat the QL responses into a more digestible format? Here's a handy demonstration of its re-layout-ing capabilities.

[mnpenner]

@r4j4h Those examples are weird. It's creating objects with two properties, key and values. If anything, I'd want the key to be the actual key for the inner object. I'm guessing that's the format needed for the D3 charts? Doesn't seem too useful for general-purpose.

Reformatting on the client isn't terrible difficult, I was just hoping to remove some of the boilerplate from the client and make it a little easier for novices. One of the nice things about GraphQL is that it's easy to read and write, which means you can give it to non-techies and they can pull out some basic data in a without having to hassle you. Having excessive nesting in the output makes it harder to read.

[He-Pin]

I have to say ,this would be nice,if this is a bad thing ,why js have it?
@mnpenner Even this is not implemented or defined,I think we will still implement it for the real case usage.

[He-Pin]

I love this one,especially I think we could scale it to larger scope.
This would help when we only have one field which is deeply en-scoped.eg
myD:a{b{c{d}}} could be rewrite to myD:a.b.c.d I would call this a Selection.

I know this would complicate the current parser implement,but it's very convenient,like the lens.

[leebyron]

This is a really interesting proposal, thanks for writing it up.

I'm curious if you're finding cases where you couldn't express something correctly before, or if this is just purely a matter of convenience? So far GraphQL has avoided convenience features as a means of avoiding feature creep, but it's also not a strict rule. Put another way: adding syntax is "expensive" and the value of having it should be well worth the cost of complexity.

Another potential concern is how this should behave when following various types. I'm not sure @benwilson512's concern is exactly correct, but it's directionally correct. Because everything in GraphQL is typed, we're not giving up type information by allowing this kind of chaining, but we could be making it more complicated. For example:

{
  clients(limit: 5) {
    id
    programsShortName: programs.shortName
  }
}

If we know programs is going to return [Program] where Program has a field called shortName of type String then we can certainly know that programs.shortName would return [String].

I'm curious if there are cases where Nullable / Non-nullable and List / Singlar typed fields can be written in this form to come up with an ambiguous or problematic type?

[mnpenner]

I'm curious if you're finding cases where you couldn't express something correctly before, or if this is just purely a matter of convenience?

Convenience. I want to keep my API flexible without having to implement a dozen variants of everything.

I could implement programShortNames, programIds and programs as fields of clients (which are all pretty commonly used) or if GraphQL allowed it, I'd just have to implement the latter and I'd get programs.shortName and programs.id for free. Well, either that or force the client to do the reformatting on their end.

I figured it would be possible to resolve the type as you suggested. I can't think of a scenario where this would be ambiguous.

Let's run through the scenarios:

programs	shortName	programs.shortName
[Program]	String	[String]
[Program!]	String	[String]
[Program!]!	String	[String]!
[Program]!	String	[String]!
[Program]	String!	[String]
[Program!]	String!	[String!]
[Program!]!	String!	[String!]!
[Program]!	String!	[String]!

The only funny scenarios are when the program can be null but the string cannot be null -- in such cases the string would be forced to be null if the program was null.

[sorenbs]

One additional aspect is performance. We expose two versions of our api - one that is relay compatible and one that is human readable. For one particular query the relay api returned 30 mb of data and the simple api returned 400 kb simply by avoiding the connection boilerplate.

This is the difference between the browser freezing for tens of seconds vs barely being noticeable. This proposal would allow us to get the same level of client side performance from the relay api.

[stubailo]

I think this is a great point - being able to short-circuit paths would make deeply nested schemas much more palatable.