Using variables / aliases / fragments / directives in queries¶

Using variables¶

In order to make a query re-usable, it can be made dynamic by using variables.

Example: Fetch an author by their author_id:

query getArticles($author_id: Int!) {
  articles(
    where: { author_id: { _eq: $author_id } }
  ) {
    id
    title
  }
}

{
  "author_id": 1
}

Using aliases¶

Aliases can be used to return objects with a different name than their field name. This is especially useful while fetching the same type of objects with different arguments in the same query.

Example: First, fetch all articles. Second, fetch the two top-rated articles. Third, fetch the worst-rated article:

query getArticles {
  articles {
    title
    rating
  }
  topTwoArticles: articles(
    order_by: {rating: desc},
    limit: 2
  ) {
    title
    rating
  }
  worstArticle: articles(
    order_by: {rating: asc},
    limit: 1
  ) {
    title
    rating
  }
}

Using fragments¶

Sometimes, queries can get long and confusing. A fragment is a set of fields with any chosen name. This fragment can then be used to represent the defined set.

Example: Creating a fragment for a set of article fields (id and title) and using it in a query:

fragment articleFields on articles {
  id
  title
}
query getArticles {
  articles {
    ...articleFields
  }
  topTwoArticles: articles(
    order_by: {rating: desc},
    limit: 2
  ) {
    ...articleFields
  }
}

Using directives¶

Directives make it possible to include or skip a field based on a boolean expression passed as a query variable.

query getArticles($with_publisher: Boolean!) {
  articles {
    title
    publisher @include(if: $with_publisher)
  }
}

{
  "with_publisher": true
}

query getArticles($with_publisher: Boolean!) {
  articles {
    title
    publisher @include(if: $with_publisher)
  }
}

{
  "with_publisher": false
}

query getArticles($with_publisher: Boolean!) {
  articles {
    title
    publisher @skip(if: $with_publisher)
  }
}

{
  "with_publisher": true
}

query getArticles($with_publisher: Boolean!) {
  articles {
    title
    publisher @skip(if: $with_publisher)
  }
}

{
  "with_publisher": false
}