GraphQL API

Endpoints

Shape of the schema

For a table author, with a to-many relationship articles:

The root types are named query_root, mutation_root and subscription_root. The subscription root mirrors the query root, and each of its fields is a live query.

Queries

query {
  author(
    where: { name: { _ilike: "%rust%" } }
    order_by: [{ created_at: desc_nulls_last }, { name: asc }]
    limit: 10
    offset: 20
  ) {
    id
    name
    articles(where: { published: { _eq: true } }, limit: 5) {
      id
      title
    }
    articles_aggregate {
      aggregate {
        count
      }
    }
  }
}

order_by takes a list of single-key objects, because ordering is ordered: {name: asc, id: desc} is one object whose two keys have no defined precedence, and the client that wrote it meant name first.

Filtering

where takes a generated <table>_bool_exp. Every comparison is named for the type it applies to, so an unknown operator or an ill-typed operand is refused by validation rather than by the database.

Combine them with _and, _or and _not, and follow a relationship by naming it. A question can also be asked about a whole related set rather than any one row of it:

{
  authors(where: { books_aggregate: { count: { predicate: { _gt: 2 } } } }) {
    name
  }
}

Over no related rows at all count is zero and the boolean folds are null — which is how “authors with no books” is written.

Mutations

mutation {
  insert_author(
    objects: [{ name: "Ada", articles: { data: [{ title: "On engines" }] } }]
    on_conflict: { constraint: author_name_key, update_columns: [name] }
  ) {
    affected_rows
    returning { id name }
  }

  update_article_by_pk(pk_columns: { id: 7 }, _set: { published: true }) {
    id
  }

  delete_article(where: { views: { _lt: 10 } }) {
    affected_rows
  }
}

Nested writes, upserts with on_conflict, update_many and the document operators are all supported. A mutation naming several root fields runs them in one transaction: if any fails, none of them happened.

Subscriptions

Each subscription field is a live query — the answer now, and the answer again whenever it changes. Connect to ws://localhost:3000/v1/graphql/ws using the graphql-transport-ws protocol.

subscription {
  article(where: { published: { _eq: true } }, order_by: [{ created_at: desc }], limit: 10) {
    id
    title
  }
}

The cursor-based half of Hasura’s subscription surface — _stream — is not implemented. See Realtime.

Authentication

A caller holding the admin secret is an administrator, and an administrator may ask to be treated as someone else. Other x-hasura-* headers become session variables that a row-level policy can read.

curl localhost:3000/v1/graphql \
  -H 'X-Hasura-Admin-Secret: shh' \
  -H 'X-Hasura-Role: user' \
  -H 'X-Hasura-User-Id: 1' \
  -d '{"query":"{ article { id title } }"}'

With a token instead, the role comes from x-hasura-default-role, and an X-Hasura-Role header may select any role listed in the token’s x-hasura-allowed-roles. That list sits inside the signature, so a caller may choose among the identities it was issued and cannot add one.

With no admin secret configured, x-hasura-* headers are ignored entirely and session variables come only from a verified token. This is a deliberate divergence from Hasura, which treats every caller on an unsecured deployment as an administrator. See Configuration.

Errors

Errors come back in Hasura’s envelope, which client code branches on. There is no data key on failure, and the path names a place in the request rather than in the response.

{
  "errors": [
    {
      "message": "field 'titel' not found in type: 'article'",
      "extensions": {
        "path": "$.selectionSet.article.selectionSet.titel",
        "code": "validation-failed"
      }
    }
  ]
}

Example request

curl -X POST http://localhost:3000/v1/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ article(limit: 5) { id title author { name } } }"}'