docs: document `table_by_pk` query

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.

[marionschleifer]

Singular and plural resolvers are already available for querying. I will update the docs on this soon 🙂

Also, renaming the singular resolvers like user_by_pk to something like user will be possible via this PR: https://github.com/hasura/graphql-engine/pull/2509.

[OLDIN]

@coco98 I know about searching by primary key, but what about searching through other columns for a single query?