Filtering topic lists in Discourse

[sam (Sam Saffron)]

This guide explains Discourse’s advanced topic filtering system, including the complete query language syntax, filter options, and how to use the /filter route effectively.

Required user level: All users

Using the Discourse topic filter query language

Discourse’s topic filter provides a powerful query language for finding topics based on multiple criteria. This advanced search interface allows you to combine filters, sort results, and create precise queries for any content on your forum.

Accessing the filter

You can access the topic filter in two ways:

Direct URL access:
Navigate to /filter on your Discourse instance (for example: https://meta.discourse.org/filter)

Sidebar navigation:
Click “More” in your sidebar, then select the filter option

The filter interface includes an intelligent autocomplete system that suggests available filters and values as you type.

Basic query syntax

Filters use a structured syntax with the format:

filter-name:value

Combine multiple filters:

category:support status:open created-after:2023-01-01

Include regular search terms:

category:support ssl certificate error

This searches for topics in the “support” category containing the words “ssl certificate error”.

Category filters

category: (alias: categories:)

Filter topics by category

Basic usage:

category:support
category:dev,support          # Topics in dev OR support categories
category:documentation:admins # Topics in admins subcategory of documentation

Advanced prefixes:

• = - Category without subcategories: =category:general
• - - Exclude category: -category:off-topic
• -= - Exclude category without subcategories: -=category:meta

Examples:

category:bug,feature          # Include bug or feature categories (with subcategories)
=category:bug,feature         # Include bug or feature categories (without subcategories)
-category:bug,feature         # Exclude bug or feature categories (with subcategories)
-=category:bug,feature        # Exclude bug or feature categories (without subcategories)

Tag filters

tag: (alias: tags:)

Filter topics by tags (requires tagging to be enabled)

Basic usage:

tag:bug
tag:feature,enhancement       # Topics with feature OR enhancement tags
tag:bug+urgent               # Topics with BOTH bug AND urgent tags

Exclusion:

-tag:solved                  # Exclude topics with solved tag
-tag:bug+urgent              # Exclude topics with both bug and urgent tags
-tag:bug,urgent              # Exclude topics with bug or urgent tags

tag_group:

Filter by tag groups

Basic usage:

tag_group:moderation
tag_group:"tag group name"   # Use quotes for names with spaces or special characters
-tag_group:staff-only        # Exclude topics with tags from staff-only group

Date filters

All date filters support both specific dates (YYYY-MM-DD) and relative days:

Activity dates

• activity-before: - Topics with last activity before date
• activity-after: - Topics with last activity after date

Creation dates

• created-before: - Topics created before date
• created-after: - Topics created after date

Latest post dates

• latest-post-before: - Topics with latest post before date
• latest-post-after: - Topics with latest post after date

Date format examples:

created-after:2023-12-25     # Specific date (YYYY-MM-DD)
created-after:30             # 30 days ago
created-after:1              # Yesterday
created-after:0              # Today

Quick suggestions:

• 1 - Yesterday
• 7 - Last week
• 30 - Last month
• 365 - Last year

User filters

created-by:

Filter by topic author (username or group name)

Basic usage:

created-by:username
created-by:user1,user2       # Topics by user1 OR user2
created-by:@username         # @ prefix is optional
created-by:me                
created-by:staff             # Topics created by members of the "staff" group

users: (alias: user:)

Filter topics where specific users have participated (posted in the topic)

Basic usage:

users:username               # Topics where username has posted
users:user1,user2            # Topics where user1 OR user2 has posted
users:user1+user2            # Topics where BOTH user1 AND user2 have posted

Exclusion:

-users:username              # Topics where username has NOT posted
-users:user1,user2           # Topics where neither user1 nor user2 has posted
-users:user1+user2           # Topics where at least one of user1 or user2 has NOT posted

group: (alias: groups:)

Filter topics where members of specific groups have participated

Basic usage:

group:staff                  # Topics where a staff group member has posted
group:staff,moderators       # Topics where a member of staff OR moderators has posted
group:staff+moderators       # Topics where members of BOTH staff AND moderators have posted

Personal filters (authenticated users only)

in:

Filter by your personal relationship to topics

Available options:

• in:pinned - Topics pinned for you
• in:bookmarked - Topics you’ve bookmarked
• in:watching - Topics you’re watching
• in:tracking - Topics you’re tracking
• in:muted - Topics you’ve muted
• in:normal - Topics with normal notification level
• in:watching_first_post - Topics in categories or tags where you watch first post
• in:new - Topics with new activity (new topics you haven’t seen + unread replies)
• in:new-topics - New topics you haven’t seen yet
• in:new-replies - Topics with unread replies
• in:unseen - Topics you haven’t viewed yet

Examples:

in:bookmarked category:support
in:watching,tracking         # Topics you're watching OR tracking
in:unseen category:welcome   # Unseen topics in the welcome category
in:new order:created         # All new activity, sorted by creation date

Numeric filters

Like filters

• likes-min: - Minimum total likes across all posts
• likes-max: - Maximum total likes across all posts
• likes-op-min: - Minimum likes on opening post
• likes-op-max: - Maximum likes on opening post

Post count filters

• posts-min: - Minimum number of posts
• posts-max: - Maximum number of posts

Participant filters

• posters-min: - Minimum number of participants
• posters-max: - Maximum number of participants

View count filters

• views-min: - Minimum view count
• views-max: - Maximum view count

Examples:

likes-min:10                 # Topics with at least 10 likes
posts-min:5 posts-max:20     # Topics with 5-20 posts
views-min:100 likes-op-min:5 # Popular topics with engaged opening posts

Status filters

status:

Filter by topic status

Available statuses:

• status:open - Open topics (not closed or archived)
• status:closed - Closed topics
• status:archived - Archived topics
• status:listed - Listed (visible) topics
• status:unlisted - Unlisted topics
• status:deleted - Deleted topics (requires permission)
• status:public - Public topics (non-restricted categories)

Plugin-specific statuses:

• status:solved - Solved topics (with Solved plugin)
• status:unsolved - Unsolved topics (with Solved plugin)

Examples:

status:open category:support
status:closed created-after:30

Locale filter

locale:

Filter topics by locale

Basic usage:

locale:en                    # Topics in English
locale:en,fr                 # Topics in English OR French
-locale:fr                   # Exclude topics in French

Sorting options

order:

Sort results by different criteria

Available sorts:

• order:activity - Latest activity (default, descending)
• order:activity-asc - Oldest activity first
• order:created - Creation date (newest first)
• order:created-asc - Oldest first
• order:latest-post - Latest post date
• order:latest-post-asc - Oldest latest post
• order:likes - Most likes across all posts
• order:likes-asc - Least likes
• order:likes-op - Most likes on opening post
• order:likes-op-asc - Least likes on opening post
• order:posters - Most participants
• order:posters-asc - Least participants
• order:title - Alphabetical by title (Z→A)
• order:title-asc - Alphabetical by title (A→Z)
• order:views - Most views
• order:views-asc - Least views
• order:hot - Highest hot score
• order:hot-asc - Lowest hot score
• order:category - Category name
• order:category-asc - Reverse category name
• order:read - Last read date (authenticated users)
• order:read-asc - Oldest read first

Advanced examples

Find popular recent discussions:

created-after:7 likes-min:10 order:likes

Support topics needing attention:

category:support status:open posts-max:3 created-after:7

Your bookmarked development topics:

category:dev in:bookmarked order:activity

Exclude solved bug reports:

category:bug -tag:solved status:open order:created

High-engagement topics from specific users:

created-by:admin,moderator likes-min:5 views-min:100

Recent unlisted topics (staff only):

status:unlisted created-after:30 order:created

Autocomplete features

The filter input provides intelligent suggestions:

1. Filter suggestions - Shows available filters as you type
2. Category autocomplete - Suggests categories by name or slug
3. Tag autocomplete - Suggests tags with post counts
4. Username autocomplete - Suggests usernames with display names
5. Date suggestions - Offers quick date options (yesterday, last week, etc.)
6. Prefix support - Shows prefix options for categories and tags

Tips and best practices

1. Use autocomplete - The filter interface provides intelligent suggestions as you type
2. Combine filters - Mix different filter types for precise results
3. Share filter URLs - Filter URLs are shareable - copy the URL to share your search
4. Add useful filters to your sidebar - Filter URLs can be added to your sidebar for easy access
5. Use exclusion - Use - prefix to exclude unwanted results
6. Date shortcuts - Use numbers for relative dates (30 = 30 days ago)
7. Keyboard navigation - Use arrow keys to navigate suggestions, Tab/Enter to select
8. Quote special characters - Use quotes for tag group names with spaces or special characters

Creating custom sidebar links

You can add filter links to your sidebar as custom links:

1. Go to your sidebar settings
2. Add a custom link with a filter URL like /filter?q=category:support status:open
3. Give it a descriptive name like “Open Support Topics”

Technical notes

• The filter uses full-text search for keywords combined with filters
• Minimum search term length applies to keyword searches
• Results are permission-aware - you only see topics you can access
• Filter queries are processed server-side for performance
• The feature supports plugin extensions for custom filters

Additional resources

• Experimental topics list filter feature
• Searching for content effectively
• Using query strings to filter topic views

[Moin]

@sam

• in:watching_first_post - Topics where you watch first post only

Is this possible? I know you can watch first posts only in a category, but how does that work on a topic?

[sam (Sam Saffron)]

Probably needs clarification, I think it will find all the topics in categories you watch first post, will update

[chapoi]

Is there a way to combine it with the classic unread/new filters too?

[sam (Sam Saffron)]

I think there is a hacky url, but I can add support for status:new-posts and topics tomorrows, not too hard

[Moin]

@sam

status

I think I’d prefer in: because it’s a personal filter like bookmarks or tracking. The status ones refer to the topic status.

@sam

think it will find all the topics in categories you watch first post

I would expect watching to return all the topics I am watching, not all topics from categories I am watching. Is that a wrong assumption? I find that confusing if watching first post refers to the category while the other statuses refer to topics.

[sam (Sam Saffron)]

We may need another operator for this watching semantics

Agree on in, I may need to amend internals a bit to support multiple in clauses

[Shauny (Shaun Robinson)]

I’d love a way to filter it by topics I have not yet viewed, and ones I have not yet replied to!

Is that possible?

For example, a filter for “Posts in the Introductions category that I have not yet replied to”.

[sam (Sam Saffron)]

post:

FEATURE: add support for -user and unseen filter

in:unseen category:welcome -user:shauny

Or even if you don’t care about unseen you could use:

category:welcome -user:shauny

[NateDhaliwal]

Is there support for things like in:first like in search? Thanks.

[sam (Sam Saffron)]

How would you see it working?

[NateDhaliwal]

For example, showing all topics with a certain keyword to hide them (rather than using search).

[sam (Sam Saffron)]

This already works:

https://meta.discourse.org/filter?q=glitchy%20category%3Abug

And so does:

https://meta.discourse.org/filter?q=glitchy%20category%3Abug%20f

But I guess if there is some other keyword like in:first hiding that is not handled by filter we can pipe it over to search…

[NateDhaliwal]

Ah, I see - f searches for that in the first post. Couldn’t find it in the doc, had to look in here. Thanks!

[tobiaseigen]

A filter I am missing is “no topic timer set to close” or “no topic timer set to close after last reply”. Does that exist and I am just not finding it?

I am using a filter linked from my sidebar to triage support topics here on meta as they start to get older without being resolved.

Here’s the filter as it looks now:

category:support status:open status:unsolved activity-before:7 assigned:nobody

It works quite well, but as you will see there are some topics listed that I have set topic timers for that I’d like to no longer see in the list.

[Shauny (Shaun Robinson)]

@sam

I can add support for status:new-posts and topics tomorrows, not too hard

Did you ever add this?

I’d love to be able to filter by topics that have unread items in, along with all my other filters. That would be my primary use for this.

[cmdntd]

@sam

Direct URL access:
Navigate to /filter on your Discourse instance (for example: Discourse Meta )

Could I use filter in category to keep cat-menu/sidebar (like doc-menu) on the left?

[NateDhaliwal]

Is it possible to filter for topics with specific text? I could use Search but the topic list is a nicer UI.