Get instant support on our discord server
Filter query results / search queries¶
Table of contents
- Equality operators (_eq and _neq)
- Greater than or less than operators (_gt, _lt, _gte, _lte)
- List based search operators (_in, _nin)
- Text search / filter or pattern matching operators
- Filter or check for null values
- Filter based on failure of some criteria
- Using multiple filters in the same query
- Filter nested objects
- Filter based on nested objects’ fields
You can use the where argument in your queries to filter results based on some field’s values (even
nested objects’ fields). You can even use multiple filters in the same where clause using the _and or the
_or operators.
For example, to fetch data for an author whose name is “Sidney”:
query {
author(
where: {name: {_eq: "Sidney"}}
) {
id
name
}
}
You can also use nested objects` fields to filter rows from a table and also filter the nested objects as well.
For example, to fetch a list of authors who have articles with a rating greater than 4 along with those articles:
query {
author (where: {articles: {rating: {_gt: 4}}}) {
id
name
articles (where: {rating: {_gt: 4}}) {
id
title
rating
}
}
}
Here _eq and _gt are examples of comparison operators that can be used in the where argument to filter on
equality.
Let’s take a look at different operators that can be used to filter results and other advanced use cases:
Equality operators (_eq and _neq)¶
The _eq (equal to) or the _neq (not equal to) operators are compatible with any Postgres type other than
json or jsonB (like Integer, Float, Double, Text, Boolean, Date/Time/Timestamp, etc.). The following are examples of
using the equality operators on different types.
Example: Integer (works with Double, Float, Numeric, etc.)¶
Fetch data about author whose id (an integer field) is equal to 3:
query {
author(
where: {id: {_eq: 3}}
) {
id
name
}
}
Example: String or Text¶
Fetch a list of authors with name (a text field) as “Sidney”:
query {
author(
where: {name: {_eq: "Sidney"}}
) {
id
name
}
}
Example: Boolean¶
Fetch a list of articles that have not been published (is_published is a boolean field):
query {
article(
where: {is_published: {_eq: false}}
) {
id
title
is_published
}
}
Example: Date (works with Time, Timezone, etc.)¶
Fetch a list of articles that were published on a certain date (published_on is a Date field):
query {
article(
where: {published_on: {_eq: "2017-05-26"}}
) {
id
title
published_on
}
}
Greater than or less than operators (_gt, _lt, _gte, _lte)¶
The _gt (greater than), _lt (less than), _gte (greater than or equal to),
_lte (less than or equal to) operators are compatible with any Postgres type other than json or jsonB
(like Integer, Float, Double, Text, Boolean, Date/Time/Timestamp, etc.). The following are examples of using these
operators on different types:
Example: Integer (works with Double, Float, etc.)¶
Fetch a list of articles rated 4 or more (rating is an integer field):
query {
article(
where: {rating: {_gte: 4}}
) {
id
title
rating
}
}
Example: String or Text¶
Fetch a list of authors whose names begin with M or any letter that follows M (essentially, a filter based on a dictionary sort):
query {
author(
where: {name: {_gt: "M"}}
) {
id
name
}
}
Example: Date (works with Time, Timezone, etc.)¶
Fetch a list of articles that were published on or after date “01/01/2018”:
query {
article(
where: {published_on: {_gte: "2018-01-01"}}
) {
id
title
published_on
}
}
List based search operators (_in, _nin)¶
The _in (in a list) and _nin (not in list) operators are used to comparing field values to a list of values.
They are compatible with any Postgres type other than json or jsonB (like Integer, Float, Double, Text, Boolean,
Date/Time/Timestamp, etc.). The following are examples of using these operators on different types:
Example: Integer (works with Double, Float, etc.)¶
Fetches a list of articles rated 1, 3 or 5:
query {
article(
where: {rating: {_in: [1,3,5]}}
) {
id
title
rating
}
}
Example: String or Text¶
Fetch a list of those authors whose names are NOT part of a list:
query {
author(
where: {name: {_nin: ["Justin","Sidney","April"]}}
) {
id
name
}
}
Text search / filter or pattern matching operators¶
The _like, _nlike, _ilike, _nilike, _similar, _nsimilar operators behave exactly like
their SQL counterparts and are used for
pattern matching on string/Text fields.
Example: _like¶
Fetch a list of articles whose titles contain the word “amet”:
query {
article(
where: {title: {_like: "%amet%"}}
) {
id
title
}
}
Example: _similar¶
Fetch a list of authors whose names begin with A or C (similar is case-sensitive):
query {
author(
where: {name: {_similar: "(A|C)%"}}
) {
id
name
}
}
Filter or check for null values¶
Checking for null values can be achieved using the _is_null operator.
Example: Filter null values in a field¶
Fetch a list of articles that have a value in the published_on field:
query {
article(
where: {published_on: {_is_null: false}}
) {
id
title
published_on
}
}
Filter based on failure of some criteria¶
The _not operator can be used to fetch results for which some condition does not hold true. i.e. to invert the
filter set for a condition
Example: _not¶
Fetch all authors who don’t have any published articles:
{
author(
where: {
_not: {
articles: { is_published: {_eq: true} }
}
}) {
id
name
articles {
title
is_published
}
}
}
Using multiple filters in the same query¶
You can group multiple parameters in the same where argument using the _and or the _or operators to filter
results based on more than one criteria.
Note
You can use the _or and _and operators along with the _not operator to create arbitrarily complex boolean
expressions involving multiple filtering criteria.
Example: _and¶
Fetch a list of articles published in a specific time-frame (for example: in year 2017):
query {
article (
where: {
_and: [
{ published_on: {_gte: "2017-01-01"}},
{ published_on: {_lte: "2017-12-31"}}
]
}
)
{
id
title
published_on
}
}
Example: _or¶
Fetch a list of articles rated more than 4 or published after “01/01/2018”:
query {
article (
where: {
_or: [
{rating: {_gte: 4}},
{published_on: {_gte: "2018-01-01"}}
]
}
)
{
id
title
rating
published_on
}
}
Filter nested objects¶
The where argument can be used in nested objects as well to filter the nested objects
Example:¶
Fetch all authors with only their 5 rated articles:
{
author {
id
name
articles(where: {rating: {_eq: 5}}) {
title
rating
}
}
}
Filter based on nested objects’ fields¶
You can use the fields of nested objects as well to filter your query results.
For example,
query {
article (where: {author: {name: {_eq: "Sidney"}}}) {
id
title
}
}
The behaviour of the comparision operators depends on whether the nested objects are a single object related via an object relationship or an array of objects related via an array relationship.
- In case of an object relationship, a row will be returned if the single nested object satisfies the defined condition.
- In case of an array relationship, a row will be returned if any of the nested objects satisfy the defined condition.
Let’s look at a few use cases based on the above:
Fetch if the single nested object defined via an object relationship satisfies a condition¶
Example:¶
Fetch all articles whose author’s name starts with “A”:
{
article (
where: {
author: {
name: { _similar: "A%"}
}
}
) {
id
title
author {
name
}
}
}
Fetch if any of the nested objects defined via an array relationship satisfy a condition¶
Example:¶
Fetch all authors which have written at least one article which is rated 1
{
author(
where: {
articles: {rating: {_eq: 1}}
}
) {
id
name
articles {
title
rating
}
}
}
Fetch if all of the nested objects defined via an array relationship satisfy a condition¶
As by default a row is returned if any of the nested objects satisfy a condition, to achieve the above we need to frame
the where expression as {_not: {inverse-of-condition}}. This reads as: fetch if not(any of the nested objects
satisfy the inverted condition) i.e. all of the nested objects satisfy the condition.
For example,
| condition | where expression |
|---|---|
{object: {field: {_eq: "value"}}} |
{_not: {object: {field: {_neq: "value"}}} |
{object: {field: {_gt: "value"}}} |
{_not: {object: {field: {_lte: "value"}}} |
Example:¶
Fetch all authors which have all of their articles published i.e. have {is_published {_eq: true}.
{
author (
where: {
_not: {
articles: {is_published: {_neq: true}}
}
}
) {
id
name
articles {
title
is_published
}
}
}
Fetch if none of the nested objects defined via an array relationship satisfy a condition¶
As by default a row is returned if any of the nested objects satisfy a condition, to achieve the above we need to frame
the where expression as {_not: {condition}}. This reads as: fetch if not(any of the nested objects
satisfy the condition) i.e. none of the nested objects satisy the condition.
For example,
| condition | where expression |
|---|---|
{object: {field: {_eq: "value"}}} |
{_not: {object: {field: {_eq: "value"}}} |
{object: {field: {_gt: "value"}}} |
{_not: {object: {field: {_gt: "value"}}} |
Example:¶
Fetch all authors which have none of their articles published i.e. have {is_published {_eq: true}.
{
author (
where: {
_not: {
articles: {is_published: {_eq: true}}
}
}
) {
id
name
articles {
title
is_published
}
}
}
