GraphQL
Tutorial 3 - Filtering the Results

17min
You shall not pass! This time, we'll look at how you can use filters to only return results based on specified rules.
Prerequisites
You have completed the Learning GraphQL tutorials 1 - 2. You can find the previous tutorial here﻿
﻿About GraphQL- optional- Read more about GraphQL and when it might be best used.
Introduction
recordsin the database have a tablewhich tells us which WebApp or Module they belong to.

This time, we'll look at how you can use filters to only return results with a particular table, or with a table which matches a certain pattern. 
Returning The Gallery WebApp
The Starter Site comes packaged with a ready-built WebApp with the id of 1 and the name webapp_1. 
Step 1: Load the previous query
We'll return to our query from the previous tutorial, but this time, we'll rename it from get_all_records  to get_webapp_1 to reflect the different purpose we intend for it. We'll also be wanting to look at page 1 again. 

Code:
GraphQL
query get_webapp_1 {
  records(
    page: 1
    per_page: 20
  ) {
    current_page
    total_pages
    results {
      table
      properties
    }
  }
}
query get_webapp_1 {
  records(
    page: 1
    per_page: 20
  ) {
    current_page
    total_pages
    results {
      table
      properties
    }
  }
}
﻿

Explorer:
﻿

Step 2: Add the filter argument
Next, we'll add a filter argument:

Code:
GraphQL
query get_webapp_1 {
  records(
    page: 1
    per_page: 20
    filter: {

    }
  ) {
    current_page
    total_pages
    results {
      table
      properties
    }
  }
}
query get_webapp_1 {
  records(
    page: 1
    per_page: 20
    filter: {

    }
  ) {
    current_page
    total_pages
    results {
      table
      properties
    }
  }
}
﻿
Notes:
As an argument for the recordsquery, this goes inside the round brackets after records.
Like the other arguments, filter is followed by a colon :
We have more settings to choose next (filter is an object) so we add curly braces { } 
Explorer:
﻿
﻿
Step 3: Filter by the table
 In this tutorial we'll choose the tableto apply the filter to, because we're looking for items with the tableof webapp_1. 

Code:
GraphQL
query get_webapp_1 {
  records(
    page: 1
    per_page: 20
    filter: {
      table: {

      }
    }
  ) {
    current_page
    total_pages
    results {
      table
      properties
    }
  }
}
query get_webapp_1 {
  records(
    page: 1
    per_page: 20
    filter: {
      table: {

      }
    }
  ) {
    current_page
    total_pages
    results {
      table
      properties
    }
  }
}
﻿
Notes:
We've chosen table as the only filter. In the next tutorial we'll explore using other fields, and filtering by more than one field at once.
This field also contains further options, so we use a colon : followed by curly braces { } to contain the next set of options.
Explorer:
﻿
﻿
Step 4: Define the filtering rule
 We now have a choice about:
How closely our value should match with the contents of a field before a match is returned. We'll use value (the exact value).
The value we are matching against. We'll use webapp_1 .
GraphQL
query get_webapp_1 {
  records(
    page: 1
    per_page: 20
    filter: {
      table: {
        value: "webapp_1"
      }
    }
  ) {
    total_pages
    results {
      table
      properties
    }
  }
}
query get_webapp_1 {
  records(
    page: 1
    per_page: 20
    filter: {
      table: {
        value: "webapp_1"
      }
    }
  ) {
    total_pages
    results {
      table
      properties
    }
  }
}
﻿
Notes: 
value is a key and is followed by a colon : 
Our value "webapp_1" must be a String, so we wrap it in double quotes.
Documentation panel: 
Selecting RecordsFilterInput gives you options for different filtering rules you can apply:
﻿
After the colons : you can see the type of value expected for each of these keys. They are mostly strings String or arrays of strings [String]. This topic will be covered in more detail in later tutorials. Keep an eye out for the different data types expected by GraphQL in the meantime.
Explorer:
When implementing this using the Explorer, the wizard will help you get the type of value correct. In this case, it provides you with quotes so that you can enter the value as a String:
﻿
 
 
Returning Items from the Blog Module
You can adjust the filter to return items from a specific Module item only. In this example, we'll specify module_3 which is the Blog Module.

Code:
GraphQL
query get_blog_module {
  records(
    page: 1
    per_page: 20
    filter: {
      table: {
        value: "module_3"
      }
    }
  ) {
    total_pages
    results {
      table
      properties
    }
  }
}
query get_blog_module {
  records(
    page: 1
    per_page: 20
    filter: {
      table: {
        value: "module_3"
      }
    }
  ) {
    total_pages
    results {
      table
      properties
    }
  }
}
﻿

Explorer:
﻿
This should return Blog Posts from the Blog Module. 
Returning Form Submissions
You can adjust the filter to return Form Submissions from a specific Form only. In this example, we'll specify form_1 which is the Newsletter Sign Up Form.

Code:
GraphQL
query get_newsletter_signups {
  records(
    page: 1
    per_page: 20
    filter: {
      table: {
        value: "form_1"
      }
    }
  ) {
    total_pages
    results {
      table
      properties
    }
  }
}
query get_newsletter_signups {
  records(
    page: 1
    per_page: 20
    filter: {
      table: {
        value: "form_1"
      }
    }
  ) {
    total_pages
    results {
      table
      properties
    }
  }
}
﻿

Explorer:
﻿
﻿
Challenge!
Introduction to GraphQL Challenges
In order to learn GraphQL, you'll need to start experimenting with what you've picked up from this tutorials. 
To help you do this, we'll now start to set you some challenges. These will ask you to tweak the examples we've given you so far and see if you can achieve the desired results. 
We'll always give you the answers to the challenge in the following Article, so don't worry if you get stuck. 
Your Challenge is to Write a Query which returns Items from all WebApps but not Module items
To carry out this challenge, you will need to create a second WebApp and add a couple of items in the Admin.
By experimenting with the options in the documentation panel, see if you can filter the results so that:
your query returns all items with the tableof webapp_1 
your query returns all items with the tableof webapp_2
your query does not return items which start with module_ 
your query does not return Form submissions which start with form_
We'll go over the answer to this challenge in the next Article. 
Next Time
We'll look at a possible solution to our challenge.
After that, we'll continue to look at filtering queries in more detail, including:
filtering by different fields, or properties
filtering with different kinds of rules
using more than one filter at once
﻿
Updated 27 Dec 2023
Did this page help you?
Tutorial 2 - Pagination
Tutorial 3 - Answers to the First Filtering Challenge