Get access to a growing collection of Premium Ghost Themes with the Yearly Subscription 🔥33% Off

How to Use Ghost Filter Expressions

Ghost Filter expressions and queries. Guide to use filtering in the Ghost CMS and an overview of the available syntax with examples and use cases in Ghost Themes.

Norbert4 min read

Filtering content is an important part of any website, and the filter parameter in Ghost Themes gives us the possibility to fetch content according to tags, authors or other properties depending on the context we are in.

Ghost CMS uses a query language called NQL to create filters for the API results.

Ghost Filter Syntax Reference

Filter Expression

A filter expression is basically a character string that defines logical expressions to be used in filtering records in a specific form.

A filter expression is formed from the following:

  • property - the field on which the filtering will be performed
  • : - separator between property and an operator-value expression
  • operator - this is optional (see below the possible values)
  • value - the value to check against


Properties have to be provided in a certain way, here are the criteria a property must respect:

  • can contain only alpha-numeric characters and _
  • cannot contain whitespace
  • must start with a letter

Other information regarding a property:

  • supports . separated inputs (ex. post.slug )
  • is always lowercase, but accepts and converts uppercase


Can be one of the following

  • null
  • true/false
  • number (integer)
  • literal, character string following these rules:
    • cannot start with -
    • cannot contain any of these symbols: '"+,()><=[] (unless they are escaped)
    • cannot contain whitespace
  • string
    • ' string ' (any character except a single or double quote surrounded by single quotes)
    • single or double quote must be escaped
    • can contain whitespace


The operators which can be used in Filter expressions:

  • - - negation
  • > - greater than
  • >= - greater than or equals
  • < - less than
  • <= - less than or equals
  • [ value1, value2, ... ] - match any value in the list of values ( can also be used in combinations with - to negate )


In order to combine multiple conditions when filtering you can use the following combinations:

  • + - AND (we get records which respect all conditions separated by +)
  • , - OR (we get records which respect at least one of the conditions separated by , )
  • ( filter expression ) - overrides operator precedence

Ghost Filter Examples

Lets see what we can achieve with filters and some use cases within Ghost Templates.

  1. One of the most common use case is fetching featured posts for your Ghost Blog.
{{!-- Get 3 featured posts --}}
{{#get "posts" filter="featured:true" limit="3"}}
  1. Fetch posts with specific tags to show a list of posts based on the assigned Tag in Ghost Admin.
{{!-- Get 3 posts which have either tech or video tag --}}
{{#get "posts" filter="tags:[tech,video]" limit="3"}}

{{!-- Get 3 posts which have either tech or video tag AND are not featured --}}
{{#get "posts" filter="tags:[tech,video]+featured:false" limit="3"}}

{{!-- Get 3 posts which have primary_tag photo OR has an image --}}
{{#get "posts" filter="primary_tag:photo,image:-null"" limit="3"}}

{{!-- Get 1 post with internal tag red --}}
{{#get "posts" filter="tags:hash-red"" limit="1"}}
  1. Fetch tags and filter by post.count

Fetch all tags, ordered by post count, where the post count is at least 1

{{!-- Fetch 5 tags which are assigned to at least 3 posts --}}
{{#get "tags" filter="post.count:>=3" order="posts.count DESC" limit="5"}}
  1. Fetch authors
{{!-- Get the 3 users with the most posts for tag tech  --}}
{{#get "posts" filter="primary_tag:tech" order="posts.count DESC"  limit="3"}}
  1. Fetch posts and filter by date
{{!-- Fetch 5 posts after a given date }}
{{#get "posts" filter="published_at:>'2020-05-10'" limit="5"}}

Ghost Filter Use Cases

Some more ideas where filters are useful:

  • Creating a related posts for your Ghost Blog, check out this tutorial to see how you can do that.
  • Creating a sidebar section with featured posts
  • Creating a tag cloud
  • Creating a list of authors by tag

Let me know if you have some other use cases in mind, I hope you found this helpful.

More in Tips & Tricks

All tips

Ghost CMS Price Helper Overview & Tips

How to use the price helper in your Ghost theme. Overview of the available options and specific use cases with examples on what you can do with the helper.

Ghost Pro Hosting

Get the best managed Ghost CMS hosting and focus on bringing value to your audience.