Talk about query { nodes(ids: [...]) { ... } }

[jsoref]

Code of Conduct

• [X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://github.com/github/docs/blob/main/content/graphql/guides/migrating-graphql-global-node-ids.md#migrating-to-the-new-global-ids

What part(s) of the article would you like to see updated?

There's a suggestion to use:

$ curl \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "X-Github-Next-Global-ID: 1" \
  https://api.github.com/graphql \
  -d '{ "query": "{ node(id: \"MDQ6VXNlcjM0MDczMDM=\") { id } }" }'

But, it'd be really helpful to suggest something fancier like the this graphql:

curl -v \
-H "Authorization: bearer $GITHUB_TOKEN" \
-H "X-Github-Next-Global-ID: 1" \
https://api.github.com/graphql \
-d \
'{"query":"query {\nnodes(ids: [\"MDEwOlJlcG9zaXRvcnkxODk2MjE2MDc=\", \"MDEyOk9yZ2FuaXphdGlvbjk5MTk=\", \"MDc6TGljZW5zZTA=\", \"MDM6QXBwMTUzNjg=\", \"MDQ6VXNlcjU4MzIzMQ==\",  ]) {\n\tid\n\t__typename\n}\n}"}'

Or even fancier

query {
nodes(ids: ["MDEwOlJlcG9zaXRvcnkxODk2MjE2MDc=", "MDEyOk9yZ2FuaXphdGlvbjk5MTk=", "MDc6TGljZW5zZTA=", "MDM6QXBwMTUzNjg=", "MDQ6VXNlcjU4MzIzMQ==",  ]) {
	id
	__typename
	... on Repository {
	 nameWithOwner
	}
	... on Organization {
		name
	}
	... on User {
		name
	}
	... on License {
		name
	}
	... on App {
		name
	}
	... on Commit {
		repository {
			nameWithOwner
		}
	}
}
}

Additional information

No response

[ramyaparimi]

@jsoref Thanks so much for opening an issue! I'll triage this for the team to review :eyes:

[skedwards88]

We want to keep these examples readable so that a user can understand the query at a glance and then extrapolate to fit their use case. If you still think that these more complex examples should be added, can you say why you would find these cases helpful?

[jsoref]

• I don't think that the multi-node query feature previously existed
• On average, the people most likely to want to use this feature are going to want to query for multiple nodes -- certainly all the instances I've seen on github.community involved people who wanted multiple nodes and had to think about how to hack through w/ graphql to make that work.

Having to twist graphql in knots in order to do something for which there's a better function is really just cruel.