GraphqlHow-ToBeginner · 4 min read

How to Implement Filtering in GraphQL: Syntax and Examples

To implement filtering in GraphQL, define query arguments that accept filter criteria, often using input types for complex filters. Then, apply these filters in your resolver functions to return only the matching data.

📐

Syntax

Filtering in GraphQL is done by adding arguments to your query fields. These arguments can be simple scalars or complex input objects that describe filter conditions.

For example, a query field might accept a filter argument of an input type that specifies fields and values to filter by.

The resolver uses these arguments to select and return only the data that matches the filter.

graphql

type Query {
  users(filter: UserFilter): [User]
}

input UserFilter {
  name: String
  ageGreaterThan: Int
  isActive: Boolean
}

type User {
  id: ID!
  name: String!
  age: Int!
  isActive: Boolean!
}

💻

Example

This example shows a GraphQL schema with a users query that accepts a filter argument. The resolver filters users by name and active status.

javascript

const { ApolloServer, gql } = require('apollo-server');

const typeDefs = gql`
  type Query {
    users(filter: UserFilter): [User]
  }

  input UserFilter {
    name: String
    isActive: Boolean
  }

  type User {
    id: ID!
    name: String!
    age: Int!
    isActive: Boolean!
  }
`;

const usersData = [
  { id: '1', name: 'Alice', age: 30, isActive: true },
  { id: '2', name: 'Bob', age: 25, isActive: false },
  { id: '3', name: 'Charlie', age: 35, isActive: true }
];

const resolvers = {
  Query: {
    users: (_, { filter }) => {
      if (!filter) return usersData;
      return usersData.filter(user => {
        if (filter.name && !user.name.includes(filter.name)) return false;
        if (filter.isActive !== undefined && user.isActive !== filter.isActive) return false;
        return true;
      });
    }
  }
};

const server = new ApolloServer({ typeDefs, resolvers });

server.listen().then(({ url }) => {
  console.log(`Server ready at ${url}`);
});

Output

Server ready at http://localhost:4000/

⚠️

Common Pitfalls

Common mistakes when implementing filtering in GraphQL include:

Not defining input types for filters, which makes queries less clear and harder to maintain.
Ignoring null or undefined filter arguments, causing unexpected results.
Applying filtering logic only on the client side instead of in resolvers, leading to inefficient data fetching.

Always validate and handle filter arguments carefully in your resolvers.

graphql

/* Wrong: No input type, filter as separate arguments */
type Query {
  users(name: String, isActive: Boolean): [User]
}

/* Right: Use input type for filters */
type Query {
  users(filter: UserFilter): [User]
}

input UserFilter {
  name: String
  isActive: Boolean
}

📊

Quick Reference

Concept	Description	Example
Filter Argument	Add arguments to query fields to accept filter criteria	`users(filter: UserFilter): [User]`
Input Types	Define complex filter structures with input types	`input UserFilter { name: String, isActive: Boolean }`
Resolver Logic	Apply filter arguments in resolver to select matching data	`usersData.filter(user => user.isActive === filter.isActive)`
Optional Filters	Handle missing or null filters gracefully	`if (!filter) return allUsers;`

✅

Key Takeaways

Use input types to define clear and reusable filter arguments in GraphQL queries.

Apply filtering logic inside resolver functions to efficiently return matching data.

Always check for null or missing filter arguments to avoid unexpected results.

Avoid putting filtering logic on the client side to reduce data transfer and improve performance.

Keep filter input types flexible to support multiple filter fields and conditions.