Filter query results by reference property in array

To filter query results by a reference property (like filtering "downloads" by a given "tag" where tags is an array of references), you'll want to use filtering within array projections using the @ operator (parent scope operator).

Here's the pattern that works:

*[_type == 'downloads']{
  'tags': tags[(@->someProperty == someValue)]->
}[length(tags) > 0]

For your specific case, if you want to filter downloads that have at least one tag matching certain criteria:

*[_type == 'downloads']{
  'tags': tags[(@->_id == "specific-tag-id")]->
}[length(tags) > 0]

The key parts here:

1. tags[(@->someProperty == condition)] - This filters the array of references inline. The @ refers to the current item in the array, and -> dereferences it to access properties of the referenced document.

2. [length(tags) > 0] - This final filter ensures you only get documents where at least one tag matched your criteria.

You can also add multiple conditions:

*[_type == 'downloads']{
  'matchingTags': tags[(@->active == true && @->category == "featured")]->
}[length(matchingTags) > 0]

Important: This syntax requires API version v2021-03-25 or later. Make sure your query client is configured to use this version:

const client = sanityClient({
  // ... other config
  apiVersion: '2021-03-25'
})

This approach is much more efficient than fetching all documents and filtering client-side, as the filtering happens at the query level in the Content Lake.