## Article Queries
**eilmeldung** features a flexible query language that can be used across multiple contexts throughout the application. Queries are useful to display specific articles or execute bulk-operations.
---
## Table of Contents
- [Quick Examples](#quick-examples)
- [Query Keys](#query-keys)
- [Search Term Types](#search-term-types)
- [Advanced Features](#advanced-features)
- [Example Queries](#example-queries)
- [Using Sort Orders in Queries](#using-sort-orders-in-queries)
- [Query Cookbook](#query-cookbook)
---
## Quick Examples
Here are some examples to get you started:
```
tag paywall title:/heise\+/ feed:heise # tags all articles from heise with titles containing "heise+" with tag paywall
read #paywall # marks all articles with the tag #paywall as read
filter newer:"1 hour ago" unread # show only unread articles which are newer than one hour
read unread feed:pitchfork summary:rap # marks all unread articles from pitchfork which contain rap (case-insensitive) as read
```
Query elements are **conjunctive** (AND-ed together), i.e., all specified conditions must be met for an article to match. To create more complex filters, use negation (`~`) or regular expressions with OR operators in case of search terms.
## Query Keys
| `read` | `read` | Match read articles | `read` |
| `unread` | `unread` | Match unread articles | `unread` |
| `marked` | `marked` | Match marked articles | `marked` |
| `unmarked` | `unmarked` | Match unmarked articles | `unmarked` |
| `tagged` | `tagged` | Match articles with at least one tag | `tagged` |
| `flagged` | `flagged` | Match flagged articles (`~flagged` for unflagged articles) | `flagged` |
| `title:` | `title:<search term>` | Match articles by title | `title:election` |
| `summary:` | `summary:<search term>` | Match articles by summary/description | `summary:"climate change"` |
| `author:` | `author:<search term>` | Match articles by author | `author:smith` |
| `feed:` | `feed:<search term>` | Match articles by feed name | `feed:techcrunch` |
| `category:` | `category:<search term>` | Match articles in a feed in the matching *direct parent* category | `category:"IT-News"` |
| `feedurl:` | `feedurl:<search term>` | Match articles by feed URL | `feedurl:example.com` |
| `feedweburl:` | `feedweburl:<search term>` | Match articles by feed website URL | `feedweburl:github.com` |
| `all:` | `all:<search term>` | Search across all fields (title, summary, author, feed) | `all:technology` |
| `tag:` | `tag:#tag1,#tag2,...` | Match articles with any of the specified tags | `tag:#important,#tech` |
| `#tag1,#tag2,...` | `#tag1,#tag2,...` | Same as `tag:#tag1,#tag2,...` | `#important,#tech` |
| `newer:` | `newer:"<time>"` | Match articles newer than specified time | `newer:"1 week ago"` |
| `older:` | `older:"<time>"` | Match articles older than specified time | `older:"2024-01-01"` |
| `today` | `today` | Match articles from the last 24 hours | `today` |
| `lastsync` | `lastsync` | Match articles from the last sync (refresh) | `lastsync` |
| `syncedbefore:` | `syncedbefore:"<time>"` | Match articles synced before specified time | `syncedbefore:"1 hour ago"` |
| `syncedafter:` | `syncedafter:"<time>"` | Match articles synced after specified time | `syncedafter:"2024-12-01"` |
## Search Term Types
- **Word**: Case-insensitive word match: `title:rust`
- **Quoted String**: Exact phrase match: `title:"Rust programming"`
- **Regular Expression**: Regex pattern match (see [regex syntax documentation](https://docs.rs/regex/latest/regex/#syntax)): `title:/^rust.*guide$/`
## Advanced Features
- **Negation**: Use `~` to negate any query (e.g., `~read` matches unread articles, `~title:politics` excludes articles with "politics" in title)
- **Multiple Criteria**: Combine multiple queries with spaces: all conditions must be satisfied (AND logic)
- **Relative Time**: Use natural language for time-based queries: `"1 week ago"`, `"yesterday"`, `"3 days ago"` (see [`parse_datetime` documentation](https://lib.rs/crates/parse_datetime) for more information)
- **Regular Expression OR**: Use the `|` operator in regex patterns for OR logic: `title:/(rust|python|javascript)/` matches articles with any of these languages in the title
## Example Queries
```
unread today # Unread articles from today
feed:bbc unread # Unread articles from BBC feed
category:"IT-News" marked # marked articles in feeds belonging to the category "IT-News"
all:"climate change" newer:"1 week ago" # Climate change articles from last week
~#politics unread # Unread articles without politics tag
author:/(?i)smith|jones|brown/ # Articles by Smith, Jones, or Brown (regex OR)
title:/(feature|bug|fix)/ feed:/github|gitlab/ # Development-related articles from code hosting platforms
lastsync unread # All unread articles from the last sync
tag flagged #readlater # Tag all flagged articles with `#readlater` (note: `tag #readlater` would also work)
```
### Using Sort Orders in Queries
Sort orders can be embedded in queries using the `sort` key. This is particularly useful in feed list queries. Check [Commands](commands.md#sorting-articles) for how sort orders are defined.
**Syntax:**
```
sort:"<sort order>"
```
**Note** the double quotes!
**Examples:**
```
unread sort:"date" # Unread articles, newest first
feed:bbc sort:"feed title" # BBC articles sorted by feed then title
today sort:"synced" # Today's articles, most recently synced first
#important unread sort:"<date" # Important unread, oldest first
newer:"1 week" sort:"feed date" # Last week's articles by feed, newest first
```
### Feed List Query Examples with Sorting
In your `feed_list` configuration, you can add sort orders to queries:
```toml
feed_list = [
'query: "Latest Unread" unread sort:"date"',
'query: "By Feed" unread sort:"feed date"',
'query: "Recently Synced" sort:"synced"',
"feeds",
"tags",
]
```
---
## Query Examples
```
# Morning news: unread articles from the last 12 hours
newer:"12 hours ago" unread
# Today's important updates
today unread #important
# Catch up on specific feeds
# Quick scan: just headlines from trusted sources
# Follow a developing story
all:"climate summit" newer:"1 week ago"
# Compare coverage across sources
title:election newer:"3 days ago"
# Track multiple related topics (case-insensitive)
# Find related content by same author
author:smith unread
```
## Bulk Operations
Queries can be used for bulk operations (article list must be focused):
```
# Mark old articles as read
:read older:"2 months ago" unread
# Mark all articles in a category as read
:read category:"IT-News"
# Tag articles from specific feeds
# Remove tag from read articles
:untag toread read
# Mark urgent items (case-insensitive)
---
## Tips & Tricks
**Combining Queries with Commands:**
- Use queries with any command that accepts a scope
- Examples: `:read <query>`, `:mark <query>`, `:tag <name> <query>`
**Testing Queries:**
- Use `:filter <query>` to preview results before bulk operations
**Saving Frequent Queries:**
- Add them to your feed list in the configuration file
- Create keybindings for common query-based commands