Docs: Expanded how to use filters in GraphQL Reference (#11017)

Summary: The GraphQL Reference will now contain information about all the
 available filter operators, with examples of how to use them.
A link to the test file /packages/gatsby/src/schema/__tests__/run-query.j
s has been added for reference.

Closes #10908

Author: RobinCsl

docs/docs/graphql-reference.md

@@ -58,6 +58,26 @@ You can also combine the mentioned operators. This query filters on `/History/`
 
 <iframe src="https://711808k40x.sse.codesandbox.io/___graphql?query=%7B%0A%20%20allMarkdownRemark(%0A%20%20%20%20filter%3A%20%7B%0A%20%20%20%20%20%20frontmatter%3A%20%7B%0A%20%20%20%20%20%20%20%20title%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20regex%3A%20%22%2FHistory%2F%22%0A%20%20%20%20%20%20%20%20%20%20ne%3A%20%22History%20of%20Magic%22%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20)%20%7B%0A%20%20%20%20totalCount%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20frontmatter%20%7B%0A%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A" width="600" height="400"></iframe>
 
+### Complete list of possible operators
+
+_In the playground below the list, there is an example query with a description of what the query does for each operator._
+
+- `eq`: short for **equal**, must match the given data exactly
+- `ne`: short for **not equal**, must be different from the given data
+- `regex`: short for **regular expression**, must match the given pattern
+- `glob`: short for **global**, allows to use wildcard `*` which acts as a placeholder for any non-empty string
+- `in`: short for **in array**, must be an element of the array
+- `nin`: short for **not in array**, must NOT be an element of the array
+- `gt`: short for **greater than**, must be greater than given value
+- `gte`: short for **greater than or equal**, must be greater than or equal to given value
+- `lt`: short for **less than**, must be less than given value
+- `lte`: short for **less than or equal**, must be less than or equal to given value
+- `elemMatch`: short for **element match**, this indicates that the field you are filtering will return an array of elements, on which you can apply a filter using the previous operators
+
+<iframe src="https://711808k40x.sse.codesandbox.io/___graphql?query=%7B%0A%20%20%23%20eq%3A%20I%20want%20all%20the%20titles%20that%20match%20%22Fantastic%20Beasts%20and%20Where%20to%20Find%20Them%22%0A%20%20example_eq%3AallMarkdownRemark(%0A%20%20%20%20filter%3A%20%7B%0A%20%20%20%20%20%20frontmatter%3A%20%7B%0A%20%20%20%20%20%20%20%20title%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20eq%3A%20%22Fantastic%20Beasts%20and%20Where%20to%20Find%20Them%22%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20)%20%7B%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20frontmatter%20%7B%0A%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%20%20%0A%20%20%23%20neq%3A%20I%20want%20all%20the%20titles%20which%20are%20NOT%20equal%20to%20the%20empty%20string%0A%20%20example_ne%3AallMarkdownRemark(%0A%20%20%20%20filter%3A%20%7B%0A%20%20%20%20%20%20frontmatter%3A%20%7B%0A%20%20%20%20%20%20%20%20title%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20ne%3A%22%22%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20)%20%7B%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%20%7B%20%20%20%20%20%20%20%20%0A%20%20%20%20%20%20%20%20frontmatter%20%7B%0A%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%20%20%0A%20%20%23%20regex%3A%20I%20want%20all%20the%20titles%20that%20do%20not%20start%20with%20%27T%27%20--%20this%20is%20what%20%2F%5E%5B%5ET%5D%2F%20means.%0A%20%20%23%20To%20learn%20more%20about%20regular%20expressions%3A%20https%3A%2F%2Fregexr.com%2F%0A%20%20example_regex%3AallMarkdownRemark(%0A%20%20%20%20filter%3A%20%7B%0A%20%20%20%20%20%20frontmatter%3A%20%7B%0A%20%20%20%20%20%20%20%20title%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20regex%3A%20%22%2F%5E%5B%5ET%5D%2F%22%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20)%20%7B%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20frontmatter%20%7B%0A%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%20%20%0A%20%20%23%20glob%3A%20I%20want%20all%20the%20titles%20that%20contain%20the%20word%20%27History%27.%0A%20%20%23%20The%20wildcard%20*%20stands%20for%20any%20non-empty%20string.%0A%20%20example_glob%3AallMarkdownRemark(%0A%20%20%20%20filter%3A%20%7B%0A%20%20%20%20%20%20frontmatter%3A%20%7B%0A%20%20%20%20%20%20%20%20title%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20glob%3A%20%22*History*%22%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20)%20%7B%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20frontmatter%20%7B%0A%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%20%20%0A%20%20%23%20in%3A%20I%20want%20all%20the%20titles%20and%20dates%20from%20%60frontmatter%60%0A%20%20%23%20where%20the%20title%20is%20either%20%0A%20%20%23%20-%20%22Children%27s%20Anthology%20of%20Monsters%22%2C%20or%0A%20%20%23%20-%20%22Hogwarts%3A%20A%20History%22.%0A%20%20example_in%3AallMarkdownRemark(%0A%20%20%20%20filter%3A%20%7B%0A%20%20%20%20%20%20frontmatter%3A%20%7B%0A%20%20%20%20%20%20%20%20title%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20in%3A%20%5B%0A%20%20%20%20%20%20%20%20%20%20%20%20%22Children%27s%20Anthology%20of%20Monsters%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22Hogwarts%3A%20A%20History%22%0A%20%20%20%20%20%20%20%20%20%20%5D%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20)%20%7B%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20frontmatter%7B%0A%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%09date%0A%20%20%20%20%20%09%09%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%20%20%0A%20%20%23%20nin%3A%20I%20want%20all%20the%20titles%20and%20dates%20from%20%60frontmatter%60%0A%20%20%23%20where%20the%20title%20is%20neither%20%0A%20%20%23%20-%20%22Children%27s%20Anthology%20of%20Monsters%22%2C%20nor%0A%20%20%23%20-%20%22Hogwarts%3A%20A%20History%22.%0A%20%20example_nin%3AallMarkdownRemark(%0A%20%20%20%20filter%3A%20%7B%0A%20%20%20%20%20%20frontmatter%3A%20%7B%0A%20%20%20%20%20%20%20%20title%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20nin%3A%5B%0A%20%20%20%20%20%20%20%20%20%20%20%20%22Children%27s%20Anthology%20of%20Monsters%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22Hogwarts%3A%20A%20History%22%0A%20%20%20%20%20%20%20%20%20%20%5D%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20)%20%7B%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20frontmatter%7B%0A%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%09date%0A%20%20%20%20%20%09%09%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%20%20%0A%20%20%23%20lte%3A%20I%20want%20all%20the%20titles%20for%20which%20%60timeToRead%60%20is%20less%20than%20or%20equal%20to%204%20minutes.%0A%20%20example_lte%3AallMarkdownRemark(%0A%20%20%20%20filter%3A%20%7B%0A%20%20%20%20%20%20timeToRead%3A%20%7B%0A%20%20%20%20%20%20%20%20lte%3A%204%0A%20%20%20%20%20%20%7D%0A%20%20%09%7D%0A%20%20)%20%7B%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20frontmatter%20%7B%0A%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%20%20%0A%20%20%23%20elemMatch%3A%20I%20want%20to%20know%20all%20the%20plugins%20that%20contain%20%22chokidar%22%20in%20their%20dependencies.%0A%20%20%23%20Note%3A%20the%20%60allSitePlugin%60%20query%20lists%20all%20the%20plugins%20used%20in%20our%20Gatsby%20site.%20%0A%20%20example_elemMatch%3A%20allSitePlugin(%0A%20%20%20%20filter%3A%7B%0A%20%20%20%20%20%20packageJson%3A%7B%0A%20%20%20%20%20%20%20%20dependencies%3A%7B%0A%20%20%20%20%20%20%20%20%20%20elemMatch%3A%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20name%3A%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20eq%3A%22chokidar%22%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%09%7D%0A%20%20)%20%7B%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%7B%0A%20%20%20%20%20%20%20%20name%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A" width="600" height="400"></iframe>
+
+If you want to understand more how these filters work, looking at the corresponding [tests](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/schema/__tests__/run-query.js) in the codebase could be very useful.
+
 ## Sort
 
 The ordering of your results can be specified with `sort`. Here the results are sorted in ascending order of `frontmatter`'s `date` field.