How to filter entries by linked references in GraphQL

Illustration of a GraphQL logo with menu options to the right of it
Published
June 15, 2021
Category

Developers

Have you ever been frustrated by not being able to filter a collection by a linked entry value using the GraphQL API? For example, do you want to filter your blog posts by linked topics such as "javascript" or "tutorial"? Check out this quick guide that shows you how to get the data you need using the linkedFrom field in your query — it’s pretty nice!

Let’s say you’re making great progress on building your new blog site. You’re using Contentful's GraphQL API and it’s a good time. You’ve written some great blog posts — and now you want a way to categorize them in your front-end application. For example, you want to show posts tagged with “JavaScript” on a single URL. Nice.

You create a new “Topic” content type, which contains text fields for name and slug.

Screenshot of Contentul tagging function

You update your blog post content model with a new field called topics, which is an array of linked references (remember type: Array<Link> for later). 

Screenshot of topics field on blog post

You add the relevant topics as links to each blog post entry. Beautiful.

Screenshot of topics on blog post entry

Here’s how the content model might look, visualized by contentmodel.io. The blog post has a field topics, which is a reference to many (n) “Topic” content types, which have fields name and slug.

Screenshot of Contentful content model

Here’s how you might display collections of blog posts per topic in your web application.

Screenshot of contentful topics in javascript

Now it’s time to construct the GraphQL query. Let’s search the docs to see how we can query the blog post collection and filter by linked topic!

Screenshot of collection filter docs

But what’s this? The documentation states that it is not possible to filter on fields of Type Array<Link>! So, what do we do?

Screenshot of Contentful filter limitations

There’s no need to rage quit! 

This type of query is made possible with the linkedFrom field! Let’s take a look at how it works.

Install the GraphQL Playground App

Let’s investigate how we can build this query in the Contentful GraphQL Playground App within the Contentful web app. Install the app by navigating to Apps and follow the instructions for installation. Authorize the app to access your Contentful account and provide it with a Content Preview API key. Click save.

Screenshot showing how to install gql playground

After installing the GraphQL Playground App, navigate to it via Apps in the navigation.

Screenshot of app link navigation

What I love about GraphQL is that it's self-documenting. Tools such as GraphQL Playground allow you to explore what data and types of queries are available on your content model. You can read the provided in-app documentation or use nifty auto-completion (we'll do that later in the post). All this functionality is made possible by GraphQL Introspection Queries. Check out this video from Shy on Introspection Queries to learn more. It’s definitely worth a watch — I learned a lot!

How to build a linkedFrom query

I like to think of a linkedFrom query as “reversing” the query you actually want to make. Instead of querying blog posts and filtering the results by linked topic, we’re going to query a single topic and fetch the blog posts that contain that topic as a linked reference.

Let’s start by querying our topicCollection. If you’ve set up the topic content type as described above with the fields name and slug, paste the query below into the GraphQL Playground App.

query {
  topicCollection {
    items {
      name
      slug
    }
  }
}

The response will include an array of items containing the name and slug properties as requested.

Screenshot of what the topic collection querty

Let’s update the query to fetch a single topic by slug — javascript.

query {
  topicCollection(where: { slug: "javascript" }, limit: 1) {
    items {
      name
      slug
    }
  }
}

Here’s the updated response.

Screenshot of topic collection query 2

What we really want to return in our query is a list of blog posts that contain the referenced topic javascript. Here’s where we can use linkedFrom — and thanks to Introspection Queries — the GraphQL Playground gives us some hints!

Screenshot of linkedfrom popup

Let’s request some fields from the blogPostCollection items that reference the javascript topic using the query below:

query {
  topicCollection(where: { slug: "javascript" }, limit: 1) {
    items {
    	linkedFrom {
        blogPostCollection {
          total
          items {
            title
            slug
            date
          }
        }
      }
    }
  }
}

And here’s the response:

Screenshot of the GraphQL response

And there you have it! 

Using the linkedFrom field is an effective way to request all entries that reference entries of Type Array<Link>. I’ve really enjoyed learning about this!

A real-world example

If you’d like to see the complete query for my topics pages, take a look at this file in the code for my personal blog site. The statically generated page is available to view here.

Is there something you’d like to learn more about to get the most out of Contentful? Come and let us know in the Community Slack. We’re a friendly bunch!

About the author

Don't miss the latest

Get updates in your inbox
A monthly newsletter to help you build better digital experiences with Contentful.
add-circle arrow-right remove style-two-pin-marker subtract-circle