Filtering
GraphCMS automatically creates filters for types you add to your content models. These filters can be applied to a single, or multiple entries, and nested object fields.
The best place to explore all available filters is by using the API Playground.
Using filters
To filter content entries, simply pass the where
argument to the query, followed by any of the filter types for the fields on your model.
All models come with their own custom GraphQL input type. Depending on the field type you want to filter by, there will be different fields you can filter by. String fields will behaviour differently to Boolean fields for example.
For example, a Post
model will have the where
input types PostWhereInput
and PostWhereUniqueInput
on the posts
, and postsConnection
query types. These types contain filters specific to that content type.
Filter types
ID
Entries can be filtered by id
.
Matches | Type | Behaviour |
---|---|---|
id | ID | Equal to |
id_not | ID | Not this |
id_in | [ID!] | One of |
id_not_in | [ID!] | Not one of |
id_starts_with | ID | Starts with |
id_not_starts_with | ID | Does not start with |
id_ends_with | ID | Ends with |
id_not_ends_with | ID | Does not end with |
id_contains | ID | Contains |
id_not_contains | ID | Does not contain |
String
All String fields can be filtered using:
Matches | Type | Behaviour |
---|---|---|
[fieldName]_not | String | Not this |
[fieldName]_in | [String] | One of |
[fieldName]_not_in | [String] | Not one of |
[fieldName]_starts_with | String | Starts with string |
[fieldName]_not_starts_with | String | Doesn't start with string |
[fieldName]_ends_with | String | Ends with string |
[fieldName]_not_ends_with | String | Doesn't end with string |
[fieldName]_contains | String | Includes string |
[fieldName]_not_contains | String | Does not include string |
Integer
All Integer fields can be filtered using:
Matches | Type | Behaviour |
---|---|---|
[fieldName]_not | Int | Not this |
[fieldName]_in | [Int] | One of |
[fieldName]_not_in | [Int] | Not one of |
[fieldName]_lt | Int | Less than |
[fieldName]_gt | Int | Greater than |
[fieldName]_lte | Int | Less than or equal to |
[fieldName]_gte | Int | Greater than or equal to |
{products(where: { quantity: 100 }) {quantity}multipleQuantities: products(where: { quantity_in: [10, 100, 1000] }) {quantity}}
Float
All Float fields can be filtered using:
Matches | Type | Behaviour |
---|---|---|
[fieldName]_not | Float | Not this |
[fieldName]_in | [Float] | One of |
[fieldName]_not_in | [Float] | Not one of |
[fieldName]_lt | Float | Less than |
[fieldName]_gt | Float | Greater than |
[fieldName]_lte | Float | Less than or equal to |
[fieldName]_gte | Float | Greater than or equal to |
{products(where: { rating: 4.5 }) {namerating}}
Boolean
All Booleans belonging to your content model can be filtered using the field name directly, as well as appended with _not
, with a Boolean input type.
Matches | Type | Behaviour |
---|---|---|
[field] | Boolean | Is |
[field]_not | Boolean | Is not |
For example, let's filter posts where the custom field verified
is true
:
{posts(where: { verified: true }) {id}posts(where: { verified_not: true }) {id}}
Date
All Date fields can be filtered using:
Matches | Type | Behaviour |
---|---|---|
[fieldName]_not | Date | Not this |
[fieldName]_in | [Date] | One of |
[fieldName]_not_in | [Date] | Not one of |
[fieldName]_lt | Date | Less than |
[fieldName]_gt | Date | Greater than |
[fieldName]_lte | Date | Less than or equal to |
[fieldName]_gte | Date | Greater than or equal to |
{today: events(where: { day: "2020-10-07" }) {day}upcoming: events(where: { day_gt: "2020-10-07" }) {day}}
DateTime
GraphCMS stores Date/DateTime fields as UTC strings, ISO 8601.
Like Date fields, DateTime fields can be filtered using:
Matches | Type | Behaviour |
---|---|---|
[fieldName]_not | DateTime | Not this |
[fieldName]_in | [DateTime] | One of |
[fieldName]_not_in | [DateTime] | Not one of |
[fieldName]_lt | DateTime | Less than |
[fieldName]_gt | DateTime | Greater than |
[fieldName]_lte | DateTime | Less than or equal to |
[fieldName]_gte | DateTime | Greater than or equal to |
{events(where: { start: "2020-10-07T09:00:00+00:00" }) {start}previous: events(where: { start_lt: "2020-10-07T09:00:00+00:00" }) {start}}
Reference
All relations (except Unions) can be filtered using filters on the fields of the model you are referencing. You can filter where every, some, and none at all match the conditions provided.
Matches | Behaviour |
---|---|
[fieldName]_every | Every reference matches |
[fieldName]_some | Some references match |
[fieldName]_none | No references match |
For example, you could fetch every post by the provided author name.
{posts(where: { authors_every: { name_in: ["John", "Simona"] } }) {titleauthors {name}}}
Null references
It is possible to filter on single, and multi reference fields for when these references are empty.
[fieldName]_every: {}
: Returns all authors, with or without connected posts[fieldName]_some: {}
: Returns all authors with at least one connected post[fieldName]_none: {}
: Returns all authors that have no posts connected
Enumeration
All Enum fields can be filtered by using:
Matches | Type | Behaviour |
---|---|---|
[fieldName]_not | EnumerationValue | Not this |
[fieldName]_in | [EnumerationValue] | One of |
[fieldName]_not_in | [EnumerationValue] | Not one of |
[fieldName]_lt | EnumerationValue | Less than |
[fieldName]_gt | EnumerationValue | Greater than |
[fieldName]_lte | EnumerationValue | Less than or equal to |
[fieldName]_gte | EnumerationValue | Greater than or equal to |
The type of enumeration you can filter by will be the actual Enumeration values defined in your schema.
{resources(where: { type_in: [Webinar, Ebook] }) {id}}
Webinar
and Ebook
are Enumeration values for field type
.
Asset
All Asset fields can be filtered using:
Matches | Type | Behaviour |
---|---|---|
[fieldName]_not | String | Not this |
[fieldName]_in | [String] | One of |
[fieldName]_not_in | [String] | Not one of |
[fieldName]_lt | String | Less than |
[fieldName]_gt | String | Greater than |
[fieldName]_lte | String | Less than or equal to |
[fieldName]_gte | String | Greater than or equal to |
[fieldName]_every | Relation Type | Every reference matches |
[fieldName]_some | Relation Type | Some references match |
[fieldName]_none | Relation Type | No references match |
Asset fields come with their own System Fields which you can apply these filters on, as well as any custom fields, or references you add.
You can filter the asset through the reference, or when querying all assets.
For example, we could fetch posts where the coverImage
field meets the provided criteria on the systme field fileName
:
{posts(where: { coverImage: { fileName: "image.png" } }) {idcoverImage {fileName}}}
Combining filters
Just like combining query arguments, it is also possible to combine filters.
{events(where: {start_gt: "2020-10-01T09:00:00+00:00"start_lt: "2020-10-31T09:00:00+00:00"fancyDress: trueprice: 100}) {startfancyDressprice}previous: events(where: { start_lt: "2020-10-07T09:00:00+00:00" }) {start}}
Conditional filters
GraphCMS supports conditional filters for your content using AND
, NOT
and OR
. Useful for filtering results basd on more than one criteria.
Conditional filters are a way to logically apply conditions of the applicable filters above. They can also be nested.
Input Type | Description |
---|---|
AND | Fetch entires that meet both conditions. |
OR | Fetch entries that match either condition. |
NOT | Fetch all entries where the conditions do not match. |
Filter by locales
When querying content entries, you can also filter by locales
:
{posts(locales: [en]) {id}}
Learn more about localization.
Filter by stage
When querying content entries, you can also filter by stage
:
{posts(stage: PUBLISHED) {idstage}}
Learn more about content stages.