Filtering - Ghost Developer Docs

https://docs.ghost.org/content-api/filtering • 277 KB fetched
Open original page

Filtering - Ghost Developer Docs
Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.

Skip to main content
Ghost Developer Docs home page

Search...

⌘ K

* Sign in

* Get Started

* Get Started

Search...

Navigation
Content API
Filtering

Home
Documentation
Migration Guides

*
Tutorials

*
Developer Forum
Getting Started

* Introduction

* Installation

* Hosting Guide

* Updates & Versions

Core Concepts

* Overview

* Architecture

* Configuration

* Staff Users

* Publishing

* Memberships

* Recommendations

* Newsletters

* Security

Themes

* Overview

* Structure

* Contexts

* Assets

* Helpers

* Content

* Search

* Share

* Members

* Routing

* Custom Settings

* GScan

Advanced Tools

* Ghost CLI

* Content API

* Overview

* Posts

* Pages

* Tags

* Authors

* Settings

* Tiers

* Parameters

* Filtering

* Pagination

* Errors

* Versioning

* JavaScript Client

* Admin API

* JAMstack

* Webhooks

Resources

* FAQ

* Breaking Changes

* Contributing

* LLM

* License

* Logos

* Trademark

On this page

* Syntax Reference

* Filter Expressions

* Property

* Value

* Operators

* Combinations

* Strings vs Literals

Advanced Tools
Content API

Filtering

Ghost uses a query language called NQL to allow filtering API results. You can filter any field or included field using matches, greater/less than or negation, as well as combining with and/or. NQL doesn’t yet support ’like’ or partial matches.
Filter strings must be URL encoded. The {{get}} helper and client library handle this for you.
At it’s most simple, filtering works the same as in GMail, GitHub or Slack - you provide a field and a value, separated by a colon.
​

Syntax Reference

​

Filter Expressions

A filter expression is a string which provides the property , operator and value in the form property: operator value :

* property - a path representing the field to filter on

* : - separator between property and an operator - value expression

* operator (optional) - how to compare values ( : on its own is roughly = )

* value - the value to match against

​

Property

Matches: [a-zA-Z_][a-zA-Z0-9_.]

* can contain only alpha-numeric characters and _

* cannot contain whitespace

* must start with a letter

* supports . separated paths, E.g. authors.slug or posts.count

* is always lowercase, but accepts and converts uppercase

​

Value

Can be one of the following

*
null

*
true

*
false

*
a number (integer)

*
a literal

* Any character string which follows these rules:

* Cannot start with - but may contain it

* Cannot contain any of these symbols: '"+,()><=[] unless they are escaped

* Cannot contain whitespace

*
a string

* ' string here ' Any character except a single or double quote surrounded by single quotes

* Single or Double quote __MUST __be escaped*

* Can contain whitespace

* A string can contain a date any format that can be understood by new Date()

*
a relative date

* Uses the pattern now-30d

* Must start with now

* Can use - or +

* Any integer can be used for the size of the interval

* Supports the following intervals: d, w, M, y, h, m, s

​

Operators

* - - not

* > - greater than

* >= - greater than or equals

* < - less than

* <= - less than or equals

* ~ - contains

* ~^ - starts with

* ~$ - ends with

* [ value, value, … ] - “in” group, can be negated with -

​

Combinations

* + - represents and

* , - represents or

* ( filter expression ) - overrides operator precedence

​

Strings vs Literals

Most of the time, there’s no need to put quotes around strings when building filters in Ghost. If you filter based on slugs, slugs are always compatible with literals. However, in some cases you may need to use a string that contains one of the other characters used in the filter syntax, e.g. dates & times contain : . Use single-quotes for these.
Suggest edits Raise issue

Parameters
Pagination

github twitter bluesky reddit
Powered by This documentation is built and hosted on Mintlify, a developer documentation platform

Links found on this page

1. /llms.txt [direct]
2. Skip to main content [direct]
3. Ghost Developer Docs home page [direct]
4. Sign in [direct]
5. Get Started [direct]
6. Home [direct]
7. Documentation [direct]
8. Migration Guides [direct]
9. Tutorials [direct]
10. Developer Forum [direct]
11. Installation [direct]
12. Hosting Guide [direct]
13. Updates & Versions [direct]
14. Overview [direct]
15. Architecture [direct]
16. Configuration [direct]
17. Staff Users [direct]
18. Publishing [direct]
19. Memberships [direct]
20. Recommendations [direct]
21. Newsletters [direct]
22. Security [direct]
23. Overview [direct]
24. Structure [direct]
25. Assets [direct]
26. Content [direct]
27. Search [direct]
28. Share [direct]
29. Members [direct]
30. Routing [direct]
31. Custom Settings [direct]
32. GScan [direct]
33. Ghost CLI [direct]
34. Overview [direct]
35. Posts [direct]
36. Pages [direct]
37. Tags [direct]
38. Authors [direct]
39. Settings [direct]
40. Tiers [direct]
41. Parameters [direct]
42. Pagination [direct]
43. Errors [direct]
44. Versioning [direct]
45. JavaScript Client [direct]
46. Webhooks [direct]
47. FAQ [direct]
48. Breaking Changes [direct]
49. Contributing [direct]
50. LLM [direct]
51. License [direct]
52. Logos [direct]
53. Trademark [direct]
54. {{get}} [direct]
55. Suggest edits [direct]
56. Raise issue [direct]
57. github [direct]
58. twitter [direct]
59. bluesky [direct]
60. reddit [direct]
61. Powered by This documentation is built and hosted on Mintlify, a developer documentation platform [direct]