
<p>Searching and filtering is a standard part of any GraphQL API. In this article, we&#8217;ll learn how to add filtering capabilities to your API by walking through a few real-world examples.</p>



<p>To learn how to handle searching and filtering on the front-end using Apollo Client, read &#8220;<a href="https://www.apollographql.com/blog/apollo-client/how-to-filter-and-search-using-variables-in-apollo-client/">How to Filter and Search using Variables in Apollo Client</a>&#8220;.</p>



<h2 class="wp-block-heading"><a href="#examples" aria-hidden="true" class="aal_anchor" id="examples"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Examples</h2>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p><strong>Searching <em>is</em> filtering</strong>: Searching and filtering are two different ways to say the same thing. The goal is to find an item (or a list of items) that matches some sort of criteria. For the rest of this post, we&#8217;ll use the word <em>filter</em> instead of search.</p>
</blockquote>



<p>For each filtering example, we&#8217;ll take a look at the originating schema, how to write a query within it, and a resolver implementation.</p>



<p>As a reminder, GraphQL is data source-agnostic. This means that you can use whatever database technology you like to fetch and save data; for instance — SQL, ORMs, NoSQL, JSON, or in-memory data all work just fine.</p>



<p>For these examples, we&#8217;ll assume we&#8217;ve stored the data <em>in-memory</em>.</p>



<h3 class="wp-block-heading"><a href="#filtering-for-a-specific-item" aria-hidden="true" class="aal_anchor" id="filtering-for-a-specific-item"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Filtering for a specific item</h3>



<p>Consider the following GraphQL schema:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  album(id: ID!): Album
}</code></pre>



<p>The <code>album</code> field expects an <code>ID</code> to be provided as an argument, and if found — it&#8217;ll return the <code>Album</code> type.</p>



<p>To fetch this, we could write a query that passes in an <code>id</code> and asks for the <code>album</code> with the <code>title</code>, <code>artist</code> and <code>genre</code> fields. The query could look like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query GetAlbumById {
  album (id: &quot;1&quot;) {
    title
    genre
    artist {
      name
    }
  }
}</code></pre>



<p>And in the <a href="https://www.apollographql.com/docs/apollo-server/data/resolvers/">resolver</a> on the server, we&#8217;d pull the <code>id</code> value out from <code>args</code> and use it to filter our data.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const resolvers = {
  Query: {
    album (parent, args, context, info) {
      const { id } = args;
      return context.db.Albums.find((a) =&gt; a.id == id)
    }
  }
} </code></pre>



<h3 class="wp-block-heading"><a href="#filtering-down-a-list" aria-hidden="true" class="aal_anchor" id="filtering-down-a-list"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Filtering down a list</h3>



<p>Now consider our GraphQL schema had an additional field on the root <code>Query</code> type to query for a <em>list</em> of albums:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  album(id: ID!): Album
  albums(genre: Genre): [Album]! # New
}</code></pre>



<p>With this new field, we can query for the list — optionally filtering it down using the <code>Genre</code> argument.</p>



<p>Here&#8217;s what a query might look like:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query GetRockAlbums {
  albums (genre: &quot;Rock&quot;) {
    title
    genre
    artist {
      name
    }
  }
}</code></pre>



<p>And the resolver:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const resolvers = {
  Query: {
    albums (parent, args, context, info) {
      const { genre } = args;
      return context.db.Albums
	.filter((a) =&gt; a.genre == genre)
    }
  }
} </code></pre>



<h3 class="wp-block-heading"><a href="#filtering-for-items-matching-a-list" aria-hidden="true" class="aal_anchor" id="filtering-for-items-matching-a-list"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Filtering for items matching a list</h3>



<p>Let&#8217;s say you wanted to get a very specific set of items and you already knew their <code>ids</code>.</p>



<p>We could adjust our GraphQL schema to look more like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  album(id: ID!): Album
  albums(genre: Genre, ids: [ID!]): [Album]! 
}</code></pre>



<p>By the way, do you notice that the parameter list is starting to get a little bit lengthy? There&#8217;s a way to clean that up, and we&#8217;ll do that soon — but first, let&#8217;s see what a query for this might look like.</p>



<p>The following query asks for albums with the ids <code>1</code>, <code>4</code>, <code>5</code>, <code>6</code>, and <code>8</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query GetAlbumsByIds {
  albums (ids: [&quot;1&quot;, &quot;4&quot;, &quot;5&quot;, &quot;6&quot;, &quot;8&quot;]) {
    title
    genre
    artist {
      name
    }
  }
}</code></pre>



<p>To handle this sort of query in the resolver, we could write it this way:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const resolvers = {
  Query: {
    album (parent, args, context, info) {
      const { ids } = args;
      return context.db.Albums.filter((a) =&gt; ids.includes(a.id))
    }
  }
} </code></pre>



<h3 class="wp-block-heading"><a href="#complex-filtering-using-an-input-type" aria-hidden="true" class="aal_anchor" id="complex-filtering-using-an-input-type"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Complex filtering using an Input Type</h3>



<p>In the last example, we started to see that the parameter list was getting long. A better approach is to design an <em>Input Type</em> containing all the possible filtering (or sorting) options necessary, and use that as a single parameter, encapsulating all of the arguments for the field.</p>



<p>Instead of this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  album(id: ID!): Album
  albums(genre: Genre, ids: [ID!]): [Album]! 
}</code></pre>



<p>Let&#8217;s try this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type AlbumsFilters = {
  genre: Genre
  ids: [ID!]
}

type AlbumsInput = {
  filter: AlbumsFilters
}

type Query {
  album(id: ID!): Album
  albums(input: AlbumsInput): [Album]! 
}</code></pre>



<p>To handle queries for <code>albums</code> in the resolver, we&#8217;d want to take care to handle both the cases of the <code>genre</code> filter being applied, the <code>ids</code> filter being applied, and both of them being applied.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const resolvers = {
  Query: {
    album (parent, args, context, info) {
      const { filter } = args;
      const shouldApplyFilters = filter !== null;

      let albums = context.db.Albums;

      if (!shouldApplyFilters) {
	return albums;
      }

      const shouldApplyGenreFilter = filter.genre !== null;
      const shouldApplyIdsFilter = filter.ids;

      if (shouldApplyGenreFilter) {
	albums = albums
          .filter((a) =&gt; a.genre === filter.genre)
      }

      if (shouldApplyIdsFilter) {
	albums = albums.filter((a) =&gt; ids.includes(a.id))
      }
		
      return albums;
    }
  }
} </code></pre>



<p>While this <em>does</em> add complexity to the resolver, it makes the querying experience much more robust.</p>



<p>Using the <em>Input Type</em> pattern, you can incrementally add more filtering (or sorting) options to your API like:</p>



<ul class="wp-block-list">
<li><strong>Filtering between ranges (greater than, less than, equal)</strong></li>



<li><strong>Conditional filtering (and, or, not, exists, etc)</strong></li>



<li><strong>Any other filtering criteria you can think of</strong></li>
</ul>



<h2 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



<p>We just walked through a few examples of how to add filter functionality to your GraphQL API. You should be all set to implement filtering in your own GraphQL API.</p>



<h3 class="wp-block-heading"><a href="#develop-your-graphql-api-with-apollo-explorer" aria-hidden="true" class="aal_anchor" id="develop-your-graphql-api-with-apollo-explorer"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Develop Your GraphQL API with Apollo Explorer</h3>



<p>Apollo Explorer is a free cloud GraphQL IDE that we built from the ground up, <strong>specifically for GraphQL developers</strong>.</p>



<p>The Explorer comes with productivity-boosting features like one-click query building, intelligent search, and the ability to extract variables and fragments.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="954" height="544" src="https://wp.apollographql.com/wp-content/uploads/2021/03/point-and-click-1.gif" alt="" class="wp-image-6849"/></figure>



<p>Apollo Explorer also comes with <a href="https://www.apollographql.com/docs/studio/dev-graphs/">development graphs</a>, which enables you to build, test, and document your schema changes locally, as well as preview graph changes in local branches and PRs.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="354" src="https://wp.apollographql.com/wp-content/uploads/2021/03/Untitled.png" alt="" class="wp-image-6851" srcset="https://wp.apollographql.com/wp-content/uploads/2021/03/Untitled.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/03/Untitled-300x104.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/03/Untitled-768x266.png 768w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>To use Apollo Explorer, head over to <a href="https://studio.apollographql.com/dev?referrer=blog">studio.apollographql.com/dev</a> and get started with your first development graph.</p>



<p>Happy querying!</p>


Filtering

GraphQL Search and Filter – How to search and filter results with GraphQL

Stay in our orbit