Query for finding un-referenced documents in Sanity.io

10 replies
Last updated: May 10, 2020
Is there a convenient GROQ query to find un-referenced documents?
AI Update

Yes! There's a great GROQ pattern for finding unreferenced documents. The key is to use the references() function in combination with count() to check if any documents reference each document.

Here's the basic pattern:

*[_type == "yourDocType"]{
  _id,
  "refs": count(*[references(^._id)])
}[refs == 0]

This query:

  1. Fetches all documents of a specific type
  2. For each document, counts how many other documents reference it using count(*[references(^._id)])
  3. Filters to only show documents where the reference count equals 0

The ^ operator is crucial here - it accesses the parent document's _id from within the subquery, allowing you to check "how many documents reference this document?"

If you just want the IDs of orphaned documents, you can simplify it:

*[_type == "offer"]{
  _id,
  "refs": count(*[references(^._id)])
}[refs == 0]._id

You can also check across multiple document types:

*[_type in ["offer", "product", "page"]]{
  _id,
  _type,
  "refs": count(*[references(^._id)])
}[refs == 0]

Performance tip: This query can be intensive on large datasets since it performs a subquery for each document. Consider running it on specific document types rather than your entire dataset, and maybe during off-peak hours if you have a lot of content.

This is particularly useful for content cleanup, identifying orphaned assets, or finding documents that might be safe to delete since nothing else depends on them. You can find more examples in the backlinks recipe which uses similar reverse reference patterns.

I tried
_type == $type && count(*[_type == "article" && references(^._id)]) == 0
but it times out..
You are looking for articles that doesn't have any references from from other articles?
Not quite - I'm looking for articles that are detached islands - not referenced from other articles or any other type of document.. This is basically for cleaning up after imports that may have gone wrong at some point.
So, say, articles not referenced from articleCollections nor issues.. (Issues nest their references to articles a few objects deep, hope this does not matter too much..)
Ah, gotcha. I guess you could base yours from this one? Does the same thing: https://github.com/sanity-io/sanity-recipes/blob/master/snippets/deleteUnusedAssets.js#L10-L15
So, say, articles not referenced from articleCollections nor issues.. (Issues nest their references to articles a few objects deep, hope this does not matter too much..)
Ah, gotcha. I guess you could base yours from this one? Does the same thing: https://github.com/sanity-io/sanity-recipes/blob/master/snippets/deleteUnusedAssets.js#L10-L15
Looks useful, thanks!
Not quite - I'm looking for articles that are detached islands - not referenced from other articles or any other type of document.. This is basically for cleaning up after imports that may have gone wrong at some point.
2nd, super useful! thank you. 🙂

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Was this answer helpful?