Filtering

Hygraph 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.

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.

StringAnchor

All String fields can be filtered using:

IntegerAnchor

All Integer fields can be filtered using:

{
  products(where: { quantity: 100 }) {
    quantity
  }

  multipleQuantities: products(where: { quantity_in: [10, 100, 1000] }) {
    quantity
  }
}

FloatAnchor

All Float fields can be filtered using:

{
  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.

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:

{
  today: events(where: { day: "2020-10-07" }) {
    day
  }

  upcoming: events(where: { day_gt: "2020-10-07" }) {
    day
  }
}

DateTimeAnchor

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

Like Date fields, DateTime fields can be filtered using:

{
  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.

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

{
  posts(where: { authors_every: { name_in: ["John", "Simona"] } }) {
    title
    authors {
      name
    }
  }
}

Null referencesAnchor

It is possible to filter on single, and multi reference fields for when these references are empty.

{
  posts(where: { author: null }) {
    id
    author {
      id
    }
  }
}

{
  posts(where: { author: {} }) {
    id
    author {
      id
    }
  }
}

• [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

{
  authors(where: { posts_none: {} }) {
    id
    posts {
      id
    }
  }
}

{
  authors(where: { posts_some: {} }) {
    id
    posts {
      id
    }
  }
}

{
  authors(where: { posts_every: {} }) {
    id
    posts {
      id
    }
  }
}

EnumerationAnchor

All Enum fields can be filtered by using:

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
  }
}

AssetAnchor

All Asset fields can be filtered using:

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

Hygraph supports conditional filters for your content using AND, NOT and OR. Useful for filtering results basd on more than one criteria.

{
  events(
    where: { AND: [{ start_gte: "2020-10-01" }, { start_lte: "2020-10-31" }] }
  ) {
    id
    start
  }
}

{
  events(where: { OR: [{ free: true }, { start_gt: "2020-10-31" }] }) {
    id
    start
  }
}

{
  events(where: { NOT: [{ free: true }, { start_gt: "2020-10-31" }] }) {
    id
    start
  }
}

{
  events(
    where: {
      OR: [
        { AND: [{ start_gte: "2020-10-01" }, { start_lte: "2020-10-31" }] }
        { id: "..." }
      ]
    }
  ) {
    id
    start
  }
}

Filter by localesAnchor

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

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

Learn more about localization.

Filter by stage argumentAnchor

When querying content entries, you can also filter by stage. The stage argument decides what document variation gets returned and searched through. Therefore, if the document does not exist in the stage variation, it gets filtered out.

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

Learn more about content stages.

Filter by content stageAnchor

Stages work a bit differently in the API than in the UI. In the UI, we use the most intuitive and editor-friendly way of treating filters. So, for instance, if you see a green PUBLISHED pill next to an entry, then this entry is only in the PUBLISHED stage. However, in the backend, our stages are organized slightly differently. The main difference is that each content entry always exists in DRAFT, and other stages are added or removed. For example, an entry that has a green PUBLISHED pill in the UI actually is in both DRAFT and PUBLISHED stages on the API side, and both versions of the entry are identical. If you update the DRAFT version but don't publish it, the entry will continue to exist in both stages, but will be marked as blue PUBLISHED in the UI.

Stages can be filtered using:

The following example includes the document in stage variation DRAFT in the result if two conditions are met:

• Of all the stage variations that exist for this document, all of them are either stage DRAFT or stage PUBLISHED and not outdated when compared to the parent variation - in this case DRAFT because we ask for the draft variation of the document.
• DRAFT is not the only existing document variation.

{
  contents(
    stage: DRAFT
    where: {
      AND: [
        {
          documentInStages_every: {
            OR: [
              { stage: DRAFT }
              {
                stage: PUBLISHED
                NOT: [{ compareWithParent: { outdated_to: true } }]
              }
            ]
          }
        }
        { NOT: [{ documentInStages_every: { stage: "DRAFT" } }] }
      ]
    }
  ) {
    id
  }
}

This next example includes the document in stage variation DRAFT in the result if one of the existing document variations is of stage PUBLISHED and this variation - Published - is not outdated compared to the parent variation - DRAFT in this case.

{
  contents(
    stage: DRAFT
    where: {
      documentInStages_some: {
        AND: [
          {
            stage: PUBLISHED
            NOT: [{ compareWithParent: { outdated_to: true } }]
          }
        ]
      }
    }
  )
}