docs: document table_by_pk query #2047
Description
Instead of query { person(where: ... ) { id } } returning an array of person, it would be nice if it returned a single object.
This pattern of duplicating interactions for both plural (arrays) and singular (objects) results can be applied to mutations as well as queries.
Example:
// before
{
users(where: {
id: {
_eq: 123
}
}) {
id
}
} // returns an array of users even if I just want one... this makes destructuring and working with these values messy
// after
{
user (where: {
id: {
_eq: 123
}
}) {
id
}
} // returns a single user object
// OR
{
users (where: {
id: {
_eq: 123
}
}) {
id
}
} // returns an array of users that might match that query
// before
mutation AddUser ($objects: [users_insert_input!]!) { // I only want to insert a single user but I have to submit the mutation as an array.
insert_users(objects: $objects) {
returning {
id
}
}
}
// after
mutation AddUser ($object: user_insert_input!) { // only inserting a single user; returning a single object
insert_user(object: $object) {
returning {
id
}
}
}
// OR
mutation AddUsers ($objects: [users_insert_input!]!) { // Sometimes I will want to add multiple users, so keep the existing queries/mutations available.
insert_users(objects: $objects) {
returning {
id
}
}
}GraphCMS does this and it's a really nice user experience. In contrast, this is really one of the few things I find actually hinders my productivity and ability to read the code with Hasura.