Strapi provides you with multiple ways to filter results on relation’s fields deeply. This article will be covering the different ways to filter results using the following APIs:

• Rest API,
• Entity Service API,
• Query Engine API, and
• GraphQL API.

Prerequisites

Before you can jump into this content, you need to have the following:

1. Basic knowledge of JavaScript
2. Basic understanding of Strapi - get started here.

Use Case

The following example will be used to demonstrate the deep filtering capabilities of Strapi:

A collection type called Book with following fields:

• title
• authors

Another collection type is called Author with the following fields:

• name
• hobby
• books

Books can have multiple Authors, and Authors can write multiple Books and have different Hobbies.

The end goal is to be able to filter Books based on their Author's Hobbies. Some dummy data will help us explore different approaches in a practice way. Consider four authors:

1
2
3
4
5
6
| ID | NAME    | HOBBY |
| -- | ------- | ----- |
| 1  | Author1 | play  |
| 2  | Author2 | sing  |
| 3  | Author3 | dance |
| 4  | Author4 | dance |

Author 1’s hobby is to play, Author 2’s is to sing, Authors 3 & 4’s hobby is to dance.

Consider the following books:

1
2
3
4
5
6
| ID | TITLE              | AUTHORS |
| -- | ------------------ | ------- |
| 1  | How to Play        | Author1 |
| 2  | How to Sing        | Author2 |
| 3  | How to Dance       | Author3 |
| 4  | How to be Flexible | Author4 |

A practical use-case can be to find all the books written by authors whose hobby contains the word dance in it, and this is what we will explore in this article.

Deep Filtering Using the Rest API

The following API Request will return all the books written by authors whose hobby contains the word dance:

Sample Request:

1
    GET /api/books?filters\[authors\][hobby][$contains]=dance 

Sample Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
    {
      "data":[
        {
          "id":3,
          "attributes":{
            "title":"How to Dance",
            ...
          }
        },
        {
          "id":4,
          "attributes":{
            "title":"How to be Flexible",
            ...
          }
        }
      ]
    }

Queries can accept a filters parameter with the following syntax: GET /api/:pluralApiId?filters\[field\][operator]=value

Strapi supports a huge range of operators in a query. A comprehensive list of query operators can be found in the Strapi documentation.

Let’s dissect the example request: GET /api/books?filters\[authors\][hobby][$contains]=dance

• The /api/books part without any query parameters would return all books (limited by the default set limit).
• The ?filters parameter offers the ability to filter results.
• [authors] is a relation field in the Book collection type.
• [hobby] is a field in the Author collection type.
• [operator] can contain an operator that Strapi supports.
• =dance is the value .

The same query can be programmatically constructed at the frontend:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
    const qs = require('qs');
    const query = qs.stringify({
      filters: {
        authors: {
          hobby: {
            $contains: dance,
          },
        },
      },
    }, {
      encodeValuesOnly: true,
    });
    
    await request(`/api/restaurants?${query}`);
    // GET /api/restaurants?filters\[authors\][hobby][$contains]=dance

Deep Filtering Using the Query Engine API

The Query Engine API offers the ability to filter results found with its findMany() method.

Results are filtered with the filters parameter, which accepts logical operators and attribute operators. Every operator should be prefixed with $.

The query equivalent of GET /api/books?filters\[authors\][hobby][$contains]=dance would be as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
    module.exports = {
      async index(ctx, next) {
        const entries = await strapi.db.query('api::book.book').findMany({
          where: {
            authors: {
              hobby: {
                $contains: 'Dance'
              },
            }
          },
        });
        ctx.body = entries;
      }
    };

In order to try out the above query, you may want to create a controller, like the way it is done in the video below.

• Run the following command in the terminal to create a controller called dancebooks:

    npx strapi generate

• Select the following options:

1
2
3
4
    ? Strapi Generators controller - Generate a controller for an API
    ? Controller name dancebooks
    ? Where do you want to add this controller? Add controller to new API
    ✔  ++ /api/dancebooks/controllers/dancebooks.js

• Create a directory for routes:

1
    src/api/dancebooks/routes

• In the routes directory, create a file called dancebooks.js and add the following route to it:

1
2
3
4
5
6
7
8
9
    module.exports = {
      routes: [
        {
          method: 'GET',
          path: '/dance-books',
          handler: 'dancebooks.index'
        }
      ]
    }

• Replace the content of src/api/dancebooks/controllers/dancebooks.js with the following lines of code: 'use strict';

1
2
3
4
5
6
7
8
9
10
11
12
13
14
     module.exports = {
      async index(ctx, next) {
        const entries = await strapi.db.query('api::book.book').findMany({
          where: {
            authors: {
              hobby: {
                $contains: 'Dance'
              },
            }
          },
        });
        ctx.body = entries;
      }
    };

Once the server restarts and a GET request to /api/dance-books is made, the expected response is received. The permission needs to be granted to the public to access the route.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
    {
      "data":[
        {
          "id":3,
          "attributes":{
            "title":"How to Dance",
            ...
          }
        },
        {
          "id":4,
          "attributes":{
            "title":"How to be Flexible",
            ...
          }
        }
      ]
    }

Deep Filtering Using the Entity Service API

The exact result can be achieved using the Entity Service API. Replace the code in src/api/dancebooks/controllers/dancebooks.js with the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
    'use strict';
    
     module.exports = {
       async index(ctx, next) {
        const entries = await strapi.entityService.findMany('api::book.book', {
          filters: {
            authors: {
              hobby: {
                $contains: 'Dance'
              },
            }
          },
        });
        ctx.body = entries;
      }
    };

The Entity Service API is built on the Query Engine API. The Entity Service is the layer that handles Strapi's complex data structures like components and dynamic zones, and uses the Query Engine API under the hood to execute database queries.

Deep Filtering Using the GraphQL API

• Install the GraphQL plugin in your Strapi project. npx strapi install graphql

• Navigate to GraphQL Playground. /graphql

The following GraphQL query will give back all the books whose author’s hobby contains the word “dance”:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
    query {
      books (filters: { authors:{hobby : { contains: "dance" }}} ){
        data {
          id
          attributes {
            authors {
              data {
                attributes {
                  hobby
                }
              }
            }
          }
        }
      }
    } 

The playground should look like the image below:

Conclusion

This article demonstrated how to filter on deeply-nested data using relationship fields in Strapi. You can learn more about these exciting features of Strapi in this excellent blog: Announcing Strapi V4. Let me know you have any suggestions and what you will be building with the knowledge.