GraphQL filter for filtering entries by linked references

Published on June 15, 2021

How to filter entries by linked references in GraphQL

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.

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.

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). 

topics field on blog post

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

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.

content model

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

javascript topics

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!

collection filters 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?

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.

install gql playground

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

app link nav

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.

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

topic collection query 1

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

Here’s the updated response.

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!

linked from popup

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

And here’s the response:

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 of a GraphQL filter

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!

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.

Related articles

An illustration of a shopping basket filled with abstract shapes representing how microservices architecture unites content and ecommerce
Guides

Create a composable commerce site with Contentful and Medusa

July 7, 2022

GraphQL is a powerful query language for your APIs. Here's how to make GraphQL HTTP requests in cURL, Python, PHP, JS, Ruby, Java, and Postman — with examples.
Guides

GraphQL via HTTP in 7 ways: cURL, Python, PHP, JS, Ruby, Java, Postman

January 14, 2021

Many approaches exist to programmatically convert HTML to Contentful content types, but what if you could use ChatGPT to accelerate the migration process?
Guides

Using ChatGPT to migrate articles from HTML to Contentful

April 4, 2024

Contentful Logo 2.5 Dark

Ready to start building?

Put everything you learned into action. Create and publish your content with Contentful — no credit card required.

Get started