API Reference - Query / Subscription

Query / subscription syntax

query|subscription [<op-name>] {
  object [([argument])]{
    object-fields
  }
}
Key Required Schema Description
op-name false Value Name query/subscription for observability
object true Object Name of the table/object
argument false Argument One or more of filter criteria, instructions for sort order or pagination

E.g. QUERY:

query {
  author(where: {articles: {rating: {_gte: 4}}} order_by: {name: asc}) {
    id
    name
  }
}

E.g. SUBSCRIPTION:

subscription {
  author(where: {articles: rating: {_gte: 4}}} order_by: {name: asc}) {
    id
    name
  }
}

Note

For more examples and details of usage, please see this.

Syntax definitions

Object

SimpleObject | AggregateObject

Simple object

object-name {
  field1
  field2
  json_field[(path: String)]
  ..
  nested object1
  nested object2
  aggregate nested object1
  ..
}
Key Required Schema Description
path false Value path argument of json/jsonb follows simple JSONPath specification. However, prefix symbol $. is optional.

E.g.

author {
   id  # scalar integer field

   name  # scalar text field

   address(path: "$.city") # scalar JSON field -> property
   address(path: "$.city.altitude") # scalar JSON field -> property -> property
   address(path: "city") # scalar JSON field -> property; '$.' prefix is optional
   contacts(path: "[0]") # scalar JSON field -> array_item
   contacts(path: "[0].phone") # scalar JSON field -> array_item_property

   article {  # nested object
     title
   }

   article_aggregate {  # aggregate nested object
     aggregate {
       count
     }
     nodes {
       title
     }
   }
}

Aggregate object

object-name_aggregate {
  aggregate {
    count
    sum {
      field
      ..
    }
    avg {
      field
      ..
    }
    stddev {
      field
      ..
    }
    stddev_samp {
      field
      ..
    }
    stddev_pop {
      field
      ..
    }
    variance {
      field
      ..
    }
    var_samp {
      field
      ..
    }
    var_pop {
      field
      ..
    }
    max {
      field
      ..
    }
    min {
      field
      ..
    }
  nodes {
    field1
    field2
    ..
    nested object1
    nested object2
    aggregate nested object1
    ..
  }
}

(For more details on aggregate functions, refer to the Postgres docs).

E.g.

author_aggregate {
  aggregate {
    count  # total count
    sum {
      id  # sum aggregate on id
    }
    avg {
      id  # avg aggregate on id
    }
    stddev {
      id  # stddev aggregate on id
    }
    stddev_samp {
      id  # stddev_samp aggregate on id
    }
    stddev_pop {
      id  # stddev_pop aggregate on id
    }
    variance {
      id  # variance aggregate on id
    }
    var_samp {
      id  # var_samp aggregate on id
    }
    var_pop {
      id  # var_pop aggregate on id
    }
    max {
      id  # max aggregate on id
    }
    min {
      id  # min aggregate on id
    }
  }

  nodes {  # objects
    id  # scalar field
    name  # scalar field

    article {  # nested object
      title
    }

    article_aggregate {  # aggregate nested object
      aggregate {
        count
      }
      nodes {
        title
      }
    }
  }
}

Argument

DistinctOnExp | WhereExp | OrderByExp | PaginationExp

DistinctOnExp

distinct_on: [ TableSelectColumnEnum ]
TableSelectColumnEnum
#example table_select_column enum for "article" table
enum article_select_column {
  id
  title
  content
  author_id
  is_published
}

WhereExp

where: BoolExp
BoolExp
AndExp | OrExp | NotExp | TrueExp | ColumnExp
AndExp
{
  _and: [BoolExp]
}

Syntactic sugar

You can simplify an _and expression by passing the sub-expressions separated by a ,.

For example:

{
  _and: [
    { rating: { _gte: 4 } },
    { published_on: { _gte: "2018-01-01" } }
  ]
}

# can be simplified to:

{
  rating: { _gte: 4 },
  published_on: { _gte: "2018-01-01" }
}
OrExp
{
  _or: [BoolExp]
}

Note

The _or operator expects an array of expressions as input. Passing an object to it will result in the behaviour of the _and operator due to the way GraphQL list input coercion behaves.

For example:

{
  _or: {
   rating: { _gte: 4 },
   published_on: { _gte: "2018-01-01" }
  }
}

# will be coerced to:

{
  _or: [
    {
      rating: { _gte: 4 },
      published_on: { _gte: "2018-01-01" }
    }
  ]
}

# which is equivalent to:

{
  _or: [
    _and: [
      { rating: { _gte: 4 } },
      { published_on: { _gte: "2018-01-01" } }
    ]
  ]
}
NotExp
{
  _not: BoolExp
}
TrueExp
{}
ColumnExp
{
  field-name : {Operator: Value }
}
Operator

Generic operators (all column types except json, jsonb):

  • _eq
  • _neq
  • _in
  • _nin
  • _gt
  • _lt
  • _gte
  • _lte

Text related operators:

  • _like
  • _nlike
  • _ilike
  • _nilike
  • _similar
  • _nsimilar

Checking for NULL values:

  • _is_null (takes true/false as values)

Type casting:

  • _cast (takes a CastExp as a value)

JSONB operators:

Operator PostgreSQL equivalent
_contains @>
_contained_in <@
_has_key ?
_has_keys_any ?|
_has_keys_all ?&

(For more details on what these operators do, refer to the Postgres docs).

PostGIS related operators on GEOMETRY columns:

Operator PostGIS equivalent
_st_contains ST_Contains
_st_crosses ST_Crosses
_st_equals ST_Equals
_st_intersects ST_Intersects
_st_overlaps ST_Overlaps
_st_touches ST_Touches
_st_within ST_Within
_st_d_within ST_DWithin

(For more details on what these operators do, refer to the PostGIS docs).

Note

  • All operators take a JSON representation of geometry/geography values as input value.

  • The input value for _st_d_within operator is an object:

    {
  field-name : {_st_d_within: {distance: Float, from: Value} }
}

Intersect Operators on RASTER columns:

  • _st_intersects_rast

Executes boolean ST_Intersects( raster <raster-column> , raster <input-raster> )

{ _st_intersects_rast: raster }
  • _st_intersects_nband_geom

Executes boolean ST_Intersects( raster <raster-column> , integer nband , geometry geommin )

This accepts st_intersects_nband_geom_input input object

{ _st_intersects_nband_geom: {nband: Integer! geommin: geometry!}
  • _st_intersects_geom_nband

Executes boolean ST_Intersects( raster <raster-column> , geometry geommin , integer nband = NULL )

This accepts st_intersects_geom_nband_input input object

{ _st_intersects_geom_nband: {geommin: geometry! nband: Integer }
CastExp
{type-name: {Operator: Value}}

Note

Currently, only casting between geometry and geography types is allowed.

OrderByExp

order_by: (TableOrderBy | [ TableOrderBy ])

E.g.

order_by: {id: desc}

or

order_by: [{id: desc}, {author: {id: asc}}]

or

order_by: {articles_aggregate: {count: asc}}
TableOrderBy

For columns:

{column: OrderByEnum}

For object relations:

{relation-name: TableOrderBy}

For array relations aggregate:

{relation-name_aggregate: AggregateOrderBy}

E.g.

Order by type for “article” table:

input article_order_by {
  id: order_by
  title: order_by
  content: order_by
  author_id: order_by
  #order by using "author" object relationship columns
  author: author_order_by
  #order by using "likes" array relationship aggregates
  likes_aggregate: likes_aggregate_order_by
}
OrderByEnum
#the order_by enum type
enum order_by {
  #in the ascending order, nulls last
  asc
  #in the ascending order, nulls last
  asc_nulls_last
  #in the ascending order, nulls first
  asc_nulls_first
  #in the descending order, nulls first
  desc
  #in the descending order, nulls first
  desc_nulls_first
  #in the descending order, nulls last
  desc_nulls_last
}
AggregateOrderBy

Count aggregate

{count: OrderByEnum}

Operation aggregate

{op_name: TableAggOpOrderBy}

Available operations are sum, avg, max, min, stddev, stddev_samp, stddev_pop, variance, var_samp and var_pop.

TableAggOpOrderBy 
{column: OrderByEnum}

PaginationExp

limit: Integer
[offset: Integer]
« previous | next »
Want to contribute or report missing content?

Powered by Sphinx. | Copyright © 2020 Hasura.