Easily restore your project to a previous version with our new Instant One-click Backup Recovery

Hygraph
Docs

Filter content

#Overview

Filtering allows you to use specific parameters to restrict the entries that display in a content table. This is helpful when trying to create a more curated overview of content.

These filters can be useful when building content views, looking for a specific type of content, or finding content that matches several parameters.

#Filter content

To filter content:

  1. Navigate to the content editor and locate the model that you want to apply filters to.
  2. Click on the + Filter button to add filters.
  3. Select a filter from the list. You can select additional fields clicking on the + button and repeating the process.

#Filters and your schema

While all projects have the default system filters, different filters may display depending on your project schema configuration.

Let's go over this with an example. Look at the following project schema for a Page model:

Filters example: The SchemaFilters example: The Schema

It has:

  • 3 single line text fields with the following names: Title, Slug, and Navigation Label.
  • 1 markdown field with the name Subtitle.
  • 8 reference fields with the names: Footer (primary), Footer (Secondary), Footer, Blocks, Hero, Seo, Marketing, and Navigation.

Filters example: The Content EditorFilters example: The Content Editor

When you go to the Content editor section of the app and select the Page model, you will see most of the fields you saw in the schema as filters, in addition to the system filters that are always there.

Some fields can't be filtered in the content editor and require a different approach through the API Playground which, in turn, requires familiarity with GraphQL, and is not usually Editor work.

#General filter conditions

In general, a filter will provide different conditions depending on the type of field configured in the schema. You will find string, boolean, enums, reference, and DateTime.

Each type offers different conditions to filter by:

#String

Strings are sequences of characters, so they are often used for text fields such as titles or descriptions. They offer the following conditions for filtering:

  • is: This condition filters for content that matches the text you enter.
  • is not: This condition filters for content that doesn't match the text you enter.
  • contains: This condition filters for content that contains the text you enter.
  • doesn't contain: This condition filters for content that doesn't contain the text you enter.
  • starts with: This condition filters for content that starts with the text you enter.
  • doesn't start with: This condition filters for content that doesn't start with the text you enter.
  • ends with: This condition filters for content that ends with the text you enter.
  • doesn't end with: This condition filters for content that doesn't end with the text you enter.

An good example of this type of filter that you can find in all projects is the ID filter.

#Boolean

Boolean fields can take two values: true and false. In all cases, booleans provide a condition dropdown, and then a second dropdown containing the true / false values.

The conditions dropdown menu for booleans contains the following options:

  • is: This condition filters for content that matches the value you select from the dropdown.
  • is not: This condition filters for content that doesn't match the value you select from the dropdown.
  • is null: This condition filters for content where no value has been assigned to the field. Selecting this makes the values dropdown field disappear from your screen.
  • is not null: This condition filters for content where a value has been assigned to the field. Selecting this makes the values dropdown field disappear from your screen.

For example, imagine you have a boolean for reviewed. Like all booleans, it can only take two values: true & false. So, if you set the filter to reviewed is true, the filter will return all entries where the reviewed boolean field has been set to true.

#Enum

Enums are lists of items. You project has them as system fields, like in the case of content stage, and may also have them as custom dropdown fields in the schema.

In all cases, enums provide a condition dropdown, and then a second dropdown containing the values configured on the list for that enum. Like this:

Enums - exampleEnums - example

The above example shows a filter where the enum is a list for product sizes.

The conditions dropdown menu for enums contains the following options:

  • is: This condition filters for content that matches the value you select from the dropdown.
  • is not: This condition filters for content that doesn't match the value you select from the dropdown.
  • is null: This condition filters for content where no value has been assigned to the field. Selecting this makes the values dropdown field disappear from your screen.
  • is not null: This condition filters for content where a value has been assigned to the field. Selecting this makes the values dropdown field disappear from your screen.

Please note that not all enums will display all the options above, some may display them partially. An example of this is the Stage filter.

#Reference

Filtering by reference is basically filtering by relation. This filter is dynamic, in the sense that it changes depending on the relational field you select, but in general terms its usage follows three steps:

  1. Select a relational field from the first dropdown menu.
  2. Select a condition from the second dropdown menu.
  3. Enter or select a value in the final field.

The references you can select for your filter depend on project configuration. All projects have the default reference filters - we'll look into them in a moment - but they can also have a number of custom ones.

Your selection will determine the fields you need to complete next to create a filter, as the Choose Relational Field dropdown will show the fields of the referenced model in the schema.

The default reference filters that all projects have are Created by, Updated by, and Published by. They are related to project users and provide the following relational fields that you can select from the dropdown:

  • IsActive: IsActive checks if the user is active or not. This is a boolean field and, as such, it offers all conditions a boolean field does, and you will be able to select true or false from the values menu.
  • Kind: Kind is an enum field that checks if the creator of a piece of content is a user or a token. As most enum fields, it offers all conditions an enum field does, and you will be able to select one of the following values from the values menu:
    • MEMBER: The content was created / updated by a user.
    • PAT: The content was created / updated by a token.
    • PUBLIC: The content was created / updated by the public API.
    • WEBHOOK: The content was created / updated by a webhook.
    • APP_TOKEN: The content was created / updated by an app.
  • Picture: This checks for pictures of the related users. This is a string field and, as such, it offers all conditions a string field does, and allows you to enter text to apply that condition to.
  • Name: This checks for names of the related users. This is a string field and, as such, it offers all conditions a string field does, and allows you to enter text to apply that condition to.
  • Updated At: This checks for date and time of update of a content entry. This is a DateTime field and, as such, it offers all conditions a DateTime field does, and allows you to select a date and time from a calendar picker.
  • Created At: This checks for date and time of creation of a content entry. This is a DateTime field and, as such, it offers all conditions a DateTime field does, and allows you to select a date and time from a calendar picker.
  • ID: This checks user IDs. This is a string field and, as such, it offers all conditions a string field does, and allows you to enter text to apply that condition to.

#DateTime

The DateTime field contains date/time information at UTC, which would look something like this 2007-12-03T10:15:30Z.

This field type offers the following conditions:

  • is: This condition returns exact matches to the date and time selected, including milliseconds. Considering this filter won't provide results unless the information provided is exact, it is recommended to stick to less than and greater than conditions for date & time.
  • is null: If your project has custom fields for date & time, and these fields are not required, then they may not always have a value assigned to them. If this is the case, using the is null filter returns all content entries where that custom date & time field does not have a value.
  • is not null: This condition returns all content entries that have a value assigned to a date and time field.
  • is not: This condition returns all entries where the date & time is not the one you provide.
  • less than: This condition returns all entries where the date & time is earlier than the one you provide.
  • less than or equal to: This condition returns all entries where the date & time is earlier than or equal to the one you provide.
  • greater than: This condition returns all entries where the date & time is later than the one you provide.
  • greater than or equal to: This condition returns all entries where the date & time is later than or equal to the one you provide.

An example of this that you can find in every project are the Created at and Updated at filters.

#How to use system filters

#Stage

Filter content by stageFilter content by stage

  1. Click on + Filter to open the filter selector.
  2. Select Stage from the menu.
  3. Use the dropdown menu next to Stage to pick a condition:
  4. Select is or is not from the first dropdown menu. These are called conditions.
  5. Select a stage from the second dropdown menu.

For example, if you select is on the first dropdown, and then PUBLISHED on the second, the filter will show you all the content entries that are currently on the PUBLISHED stage.

It is not necessary to type in a keyword in the search field for this filter to work, so you can use the filter on its own to return search results on all the content in that model, or you can use it to narrow down a search that uses keywords.

#ID

An ID is a unique identifier of your content entry that is assigned to it when you first save it. You can see it on the sidebar in the edit screen, under Entry information.

Content entry IDContent entry ID

If you know the ID of a content entry you are looking for - totally or partially - you can use that to quickly find it using the ID filter.

Filter content by IDFilter content by ID

  1. Click on + Filter to open the filter selector.

  2. Select ID from the menu.

  3. Use the dropdown menu next to ID to pick a condition:

    • is
    • is not
    • contains
    • doesn't contain
    • starts with
    • doesn't start with
    • ends with
    • doesn't end with

  4. Enter a value in the text field next to the conditions dropdown.

Some examples

Imagine we are looking for a content entry with the ID clgm2kql0bspm0burfoqjqhdl:

  • If you know the exact ID, you could simply use is clgm2kql0bspm0burfoqjqhdl as a filter. This would return only one result, the exact content entry you're looking for.
  • If you know the the ID starts with clgm, you could use starts with cglm as a filter. This would return all content entries that have IDs that start with cglm.
  • If you know the ID ends in qhdl, you could use ends with qhdl as a filter. This would return all content entries that have IDs that end with qhdl.

#Created / Updated at

The Created at and Updated at filter look at DateTime fields in the content entry. This can be the date of creation/update, as well as any DateTime field in the schema configuration for the model.

Filter content by Created atFilter content by Created at

  1. Click on + Filter to open the filter selector.
  2. Select Created at, or Updated at from the menu.
  3. Use the dropdown menu to pick a condition:
    • is: This condition returns exact results to the information you select on the calendar field next to it, including milliseconds. Considering this filter won't provide results unless the information provided is exact, it is recommended to stick to less than and greater than conditions for date & time.
    • is null: If your project has custom fields for date & time, and these fields are not required, then they may not always have a value assigned to them. If this is the case, using the is null filter returns all content entries where that custom date & time field does not have a value.
    • is not null: This condition returns all content entries that have a value assigned to a date and time field.
    • is not: This condition returns all entries where the date & time is not the one you provided in the calendar field.
    • less than: This condition returns all entries where the date & time is earlier than the one you provided in the calendar field.
    • less than or equal to: This condition returns all entries where the date & time is earlier than or equal to the one you provided in the calendar field.
    • greater than: This condition returns all entries where the date & time is later than the one you provided in the calendar field.
    • greater than or equal to: This condition returns all entries where the date & time is later than or equal to the one you provided in the calendar field.
  4. Enter a value in the calendar field next to the conditions dropdown. If you need additional help selecting a date & time using the calendar, we have documentation on the Date and time field that explains it in detail.

#Created / Updated / Published by

These filters take a list of project users, and compare a value you provide to relational fields in the project, so - in a way - this would be filtering by relations.

Filter content by Created byFilter content by Created by

This filter is dynamic, in the sense that it changes depending on the relational field you select, but in general terms its usage follows three steps:

  1. Click on + Filter to open the filter selector.
  2. Select Created by, Updated by, or Published by from the Choose Relational Field dropdown menu.
  3. Use the dropdown menu next to the relational field you selected to pick a condition. You options are:
    • IsActive: IsActive checks if the user is active or not.
    • Kind: Kind is an enum field that checks if the creator of a piece of content is a user or a token.
    • Picture: This checks for pictures of the related users.
    • Name: This checks for names of the related users.
    • ID: This checks user IDs.
  4. Enter or select a value in the final field. You options here depend on what you selected in the previous field:
    • If you selected IsActive: This is a boolean field and, as such, it offers all conditions a boolean field does, and you will be able to select true or false from the values menu.
    • If you selected Kind: As most enum fields, it offers all conditions an enum field does, and you will be able to select one of the following values from the values menu:
      • MEMBER: The content was created / updated by a user.
      • PAT: The content was created / updated by a token.
      • PUBLIC: The content was created / updated by the public API.
      • WEBHOOK: The content was created / updated by a webhook.
      • APP_TOKEN: The content was created / updated by an app.
    • If you selected Picture: This is a string field and, as such, it offers all conditions a string field does, and allows you to enter text to apply that condition to.
    • If you selected Name: This is a string field and, as such, it offers all conditions a string field does, and allows you to enter text to apply that condition to.
    • If you selected Updated At: This is a DateTime field and, as such, it offers all conditions a DateTime field does, and allows you to select a date and time from a calendar picker.
    • If you selected Created At: This is a DateTime field and, as such, it offers all conditions a DateTime field does, and allows you to select a date and time from a calendar picker.
    • If you selected ID: This is a string field and, as such, it offers all conditions a string field does, and allows you to enter text to apply that condition to.