How to Use Ghost Filter Expressions

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

Property

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

Value

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

Operators

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 )

Combinations

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.