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 filtersAnchor

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 typesAnchor

IDAnchor

Entries can be filtered by id.

MatchesTypeBehaviour
idIDEqual to
id_notIDNot this
id_in[ID!]One of
id_not_in[ID!]Not one of
id_starts_withIDStarts with
id_not_starts_withIDDoes not start with
id_ends_withIDEnds with
id_not_ends_withIDDoes not end with
id_containsIDContains
id_not_containsIDDoes not contain

StringAnchor

All String fields can be filtered using:

MatchesTypeBehaviour
[fieldName]_notStringNot this
[fieldName]_in[String]One of
[fieldName]_not_in[String]Not one of
[fieldName]_starts_withStringStarts with string
[fieldName]_not_starts_withStringDoesn't start with string
[fieldName]_ends_withStringEnds with string
[fieldName]_not_ends_withStringDoesn't end with string
[fieldName]_containsStringIncludes string
[fieldName]_not_containsStringDoes not include string

IntegerAnchor

All Integer fields can be filtered using:

MatchesTypeBehaviour
[fieldName]_notIntNot this
[fieldName]_in[Int]One of
[fieldName]_not_in[Int]Not one of
[fieldName]_ltIntLess than
[fieldName]_gtIntGreater than
[fieldName]_lteIntLess than or equal to
[fieldName]_gteIntGreater than or equal to
{
products(where: { quantity: 100 }) {
quantity
}
multipleQuantities: products(where: { quantity_in: [10, 100, 1000] }) {
quantity
}
}

FloatAnchor

All Float fields can be filtered using:

MatchesTypeBehaviour
[fieldName]_notFloatNot this
[fieldName]_in[Float]One of
[fieldName]_not_in[Float]Not one of
[fieldName]_ltFloatLess than
[fieldName]_gtFloatGreater than
[fieldName]_lteFloatLess than or equal to
[fieldName]_gteFloatGreater than or equal to
{
products(where: { rating: 4.5 }) {
name
rating
}
}

BooleanAnchor

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.

MatchesTypeBehaviour
[field]BooleanIs
[field]_notBooleanIs 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
}
}

DateAnchor

All Date fields can be filtered using:

MatchesTypeBehaviour
[fieldName]_notDateNot this
[fieldName]_in[Date]One of
[fieldName]_not_in[Date]Not one of
[fieldName]_ltDateLess than
[fieldName]_gtDateGreater than
[fieldName]_lteDateLess than or equal to
[fieldName]_gteDateGreater than or equal to
{
today: events(where: { day: "2020-10-07" }) {
day
}
upcoming: events(where: { day_gt: "2020-10-07" }) {
day
}
}

DateTimeAnchor

GraphCMS stores Date/DateTime fields as UTC strings, ISO 8601.

Like Date fields, DateTime fields can be filtered using:

MatchesTypeBehaviour
[fieldName]_notDateTimeNot this
[fieldName]_in[DateTime]One of
[fieldName]_not_in[DateTime]Not one of
[fieldName]_ltDateTimeLess than
[fieldName]_gtDateTimeGreater than
[fieldName]_lteDateTimeLess than or equal to
[fieldName]_gteDateTimeGreater 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
}
}

ReferenceAnchor

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.

MatchesBehaviour
[fieldName]_everyEvery reference matches
[fieldName]_someSome references match
[fieldName]_noneNo references match

For example, you could fetch every post by the provided author name.

{
posts(where: { authors_every: { name_in: ["John", "Simona"] } }) {
title
authors {
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

EnumerationAnchor

All Enum fields can be filtered by using:

MatchesTypeBehaviour
[fieldName]_notEnumerationValueNot this
[fieldName]_in[EnumerationValue]One of
[fieldName]_not_in[EnumerationValue]Not one of
[fieldName]_ltEnumerationValueLess than
[fieldName]_gtEnumerationValueGreater than
[fieldName]_lteEnumerationValueLess than or equal to
[fieldName]_gteEnumerationValueGreater 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.

AssetAnchor

All Asset fields can be filtered using:

MatchesTypeBehaviour
[fieldName]_notStringNot this
[fieldName]_in[String]One of
[fieldName]_not_in[String]Not one of
[fieldName]_ltStringLess than
[fieldName]_gtStringGreater than
[fieldName]_lteStringLess than or equal to
[fieldName]_gteStringGreater than or equal to
[fieldName]_everyRelation TypeEvery reference matches
[fieldName]_someRelation TypeSome references match
[fieldName]_noneRelation TypeNo 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" } }) {
id
coverImage {
fileName
}
}
}

Combining filtersAnchor

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: true
price: 100
}
) {
start
fancyDress
price
}
previous: events(where: { start_lt: "2020-10-07T09:00:00+00:00" }) {
start
}
}

Conditional filtersAnchor

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 TypeDescription
ANDFetch entires that meet both conditions.
ORFetch entries that match either condition.
NOTFetch all entries where the conditions do not match.

Filter by localesAnchor

When querying content entries, you can also filter by locales:

{
posts(locales: [en]) {
id
}
}

Learn more about localization.

Filter by stageAnchor

When querying content entries, you can also filter by stage:

{
posts(stage: PUBLISHED) {
id
stage
}
}

Learn more about content stages.

Did you find this page useful?

Your feedback helps us improve our docs, and product.