Contentful logo

Contentful Community

Searching on multiple-reference fields


The documentation for searching on references notes the following restriction:

You can only search on references on fields which link to a single entry. Fields which hold references to many entries or fields with references to assets are not supported.

To work around this we can fetch all entries, then filter by references within our application, but this is inefficient and precludes pagination.

Given this limitation, this knowledgebase article is misleading. It would be reasonable assumption that a Movie content type would allow multiple Actor references. However, the example provided would only work with a single-reference actors field.

Are there plans to remove this limitation in a future version?



Hi @matt.burtch,

That’s right. Need to think of a better example…
Could you please share your case? Is searching by multiple-reference fields the only approach?



Hey @andrey,

Our current model includes Categories and Posts: posts can belong to multiple categories, and categories have additional content (e.g. description, images, etc). Fetching posts by category references becomes problematic due to the restriction.

Another example would be adding authors to posts, then finding posts by an author reference.

There are other approaches, but none as straightforward from a content-authoring standpoint. We could use an intermediate Text/List checkbox field whose hard-coded values match category slugs, but adding/renaming categories would result in discrepancies.

1 Like


Hey @matt.burtch ,

Thanks for the explanation!
You listed one of the approaches which should address this problem:

Another example would be adding authors to posts, then finding posts by an author reference.

Finding by author is something we suggested in similar cases. The scenario itself looks more natural, from how it’s setup point of view: each entry is linked with its author > searching by author shows you all entries belong to certain author.

What do you think?



Hey @andrey, @matt.burtch,

Just tried what Andrey proposed and it works perfectly. But lets say I want to get the actors infos in the same request for the files so I don’t have to make a second request. Is it currently possible ?
The point would be to have an object like so:

{ // the actor object
  name: 'dany trejo',
  birth: '01/ 01/ 1900'
  movies: [ { // the related movies objects
      name: 'machete'
    }, {
      name: 'machete in space'
    }, ...



I’m very confused by your response on Oct 20. @matt.burtch gave 2 examples… in one example, there was an author/post relationship, and in the other example, there was a category/post relationship. A post is likely to only have one author, but it could have multiple categories. I have the exact same situation where I want to search by category, where category is a multiple-reference field. Can you confirm that this is impossible, or is there some way around this limitation?



@matt.burtch @andrey

I agree, super misleading. Basically, in the example Matt points out, if the “actors” field on a “Movie” is a multi-reference, instead of a single reference, the api would error out with the following message:

You are trying to search on a reference to an unsupported type. You can only search on references to single entries

However, one thing I would point out… if you actually know the ID of the Actor, you can still search for on multi-reference fields by id.

Meaning, if all you’re trying to do is find all Movies that Danny Trejo was in, and you know what his ID is, you could adapt the query to the following, which should work:


Another idea to consider is to add an intermediate content type between Movie and Actor; call it MovieActor. This content type consists of a single reference to a Movie and a single reference to an Actor. With this type of hierarchy it is possible to search for all MovieActor entries which reference Danny Trejo and the resulting API response will include all the movies. Think of it as a join table for content types. In this situation, the Actor content type as well as the Movie content type both would not have references to the other.

This is certainly not a recommended approach for most situations and would be quite cumbersome in the editorial experience, but we have had some customers use this successfully.



Hi, did anyone find a solution to this issue? It seems strange that we cant search with multi references.



As @jason1 suggested, you can search for multi-reference fields by id.
Here is a code example to search all blog articles with the “billing” tag:

    async asyncData ({ env, params, error }) {
      let tag = await client.getEntries({
        'content_type': 'tags',
        'fields.slug': 'billing'

      if (! return error({ statusCode: 404, message: 'Tag not found' })

      let posts = await client.getEntries({
        'content_type': 'blogPost',
        '': tag.items[0]

      return {
        posts: posts.items,
        tag: tag.items[0]