What Is a GROQ Filter and How Do You Write One?

Suppose you are building a blog with Sanity and need to fetch posts for a public-facing listing page. You want to show only published posts, ordered by date, with a featured image. Here is how you would build that filter step by step.

Step 1 — Filter by Document Type

*[_type == "post"]

This returns every document of type "post" in your dataset. It's the starting point for almost every blog query.

Step 2 — Add a Published Date Filter

*[_type == "post" && publishedAt < now()]

Now only posts with a publishedAt date in the past are returned. Future-dated posts (scheduled content) are automatically excluded.

Step 3 — Require a Featured Image

*[_type == "post" && publishedAt < now() && defined(mainImage)]

Adding defined(mainImage) ensures that posts without a featured image are excluded from the listing — preventing broken UI cards.

Step 4 — Add Ordering and Projection

*[_type == "post" && publishedAt < now() && defined(mainImage)] | order(publishedAt desc) {
  _id,
  title,
  slug,
  publishedAt,
  mainImage,
  "authorName": author->name,
  "categoryTitle": category->title
}

The final query combines the filter with an ordering pipe and a projection. The projection (the curly braces) selects only the fields you need, keeping the response payload lean. The -> operator dereferences the author and category references inline.

Step 5 — Using the Query in JavaScript

import { createClient } from '@sanity/client'

const client = createClient({
  projectId: 'your-project-id',
  dataset: 'production',
  useCdn: true,
  apiVersion: '2024-01-01',
})

const query = `*[_type == "post" && publishedAt < now() && defined(mainImage)]
  | order(publishedAt desc) {
    _id,
    title,
    slug,
    publishedAt,
    mainImage,
    "authorName": author->name,
    "categoryTitle": category->title
  }`

const posts = await client.fetch(query)
console.log(posts)

This pattern — filter, order, project — is the standard structure for most GROQ queries in production Sanity applications. The filter does the heavy lifting of narrowing the dataset before any data is transferred to the client.

Misconception 1: GROQ Filters Run on the Client

GROQ filters are evaluated entirely server-side by Sanity's Content Lake. The client never receives the full dataset and then filters it locally. This means even complex filters on large datasets are efficient — only matching documents are returned over the network.

Misconception 2: You Need a Filter to Get All Documents

You can write * without any filter brackets to retrieve all documents in a dataset. However, this is almost never what you want in production — it returns every document of every type, including system documents. Always add at least a _type filter.

Misconception 3: == and = Are Interchangeable

GROQ uses == for equality checks, not a single =. Using a single = in a filter will cause a query parse error. This is a common mistake for developers coming from SQL or other query languages where = is the equality operator.

Misconception 4: Filters Can Access Joined Data Without Dereferencing

If a field is a reference to another document, you cannot filter on the referenced document's fields without using the -> dereference operator. Writing *[_type == "post" && author.name == "Jane"] will not work — author is a reference, not an embedded object. The correct form is *[_type == "post" && author->name == "Jane"].

Misconception 5: match() Is a Full-Text Search Engine

The match() function performs simple pattern matching, not ranked full-text search. It does not score results by relevance, handle stemming, or support fuzzy matching. For production search functionality, use Sanity's dedicated search API or integrate a third-party search provider like Algolia or Typesense.

Misconception 6: Filters and Projections Are the Same Thing

A filter (inside []) determines which documents are returned. A projection (inside {}) determines which fields of those documents are returned. They are separate concepts. You can have a filter without a projection (returns full documents) or a projection without a filter (shapes all documents). Confusing the two leads to either over-fetching data or writing invalid query syntax.