Find Files Based on Frontmatter

This optional criteria determines which files will be processed by your rule. Only files whose frontmatter matches this criteria will be modified. Leave empty to process all files in scope.

Basic Syntax

Enter criteria directly without "IF":

<field> <operator> <value>

The plugin automatically evaluates your criteria to determine which files match.

Comparison Operators

Equality

status = "draft"          # Equals
status != "archived"      # Not equals

Numeric Comparisons

count > 10                # Greater than
count < 5                 # Less than
priority >= 3             # Greater than or equal
priority <= 7             # Less than or equal

Date Comparisons

created_date > "2025-01-01"
deadline < "{{today}}"

Logical Operators

AND

Both criteria must be true:

tags contains "project" AND status = "active"

OR

Either criteria can be true:

priority = "high" OR deadline < "{{today}}"

NOT

Negates a criteria:

NOT HAS completed_date
NOT tags contains "archived"

Special Operators

contains

Check if an array contains a value:

tags contains "important"
categories contains "work"

HAS

Check if a field exists:

HAS custom_field
NOT HAS completed_date

IN

Check if a value is in a list:

status IN ["draft", "review", "published"]
priority IN [1, 2, 3]

Advanced Operators

Advanced Features

The operators in this section are powerful condition operators that let you query and validate your frontmatter data with precision.

.length - Count Items or Characters

Get the length of arrays, strings, or objects:

Arrays (count items):

tags.length > 0           # Has at least one tag
tags.length = 3           # Exactly 3 tags
tags.length >= 5          # 5 or more tags

Strings (count characters):

title.length < 50         # Title shorter than 50 characters
content.length > 1000     # Long content

Objects (count keys):

metadata.length > 5       # More than 5 metadata fields

Real-world examples:

# Find notes with many tags
tags.length >= 10

# Find short titles
title.length < 20

# Find notes with minimal metadata
metadata.length < 3

empty / !empty - Check for Empty Values

Check if arrays, strings, or objects are empty:

Arrays:

tags empty                # Empty array: []
tags !empty               # Has items: [item1, item2]

Strings:

note empty                # Empty string: ""
note !empty               # Has content

Objects:

metadata empty            # Empty object: {}
metadata !empty           # Has fields

Important distinctions:

• Field missing: field !exists (not empty)
• Field is null: field :null (not empty)
• Field is empty array/string/object: field empty

Examples:

# Find notes with empty tags (different from missing tags)
tags empty

# Find notes with some content
content !empty

# Combine with other operators
tags exists AND tags !empty     # Has tags and they're not empty

Type Checking - Validate Field Types

Check if a field is a specific data type:

Available types:

• :string - Text values
• :number - Numeric values
• :boolean - true/false values
• :array - Arrays
• :object - Objects
• :null - Null values

Syntax:

field :type              # Field is of type
field !:type             # Field is NOT of type (negated)

Examples:

# Validate field types
status :string           # Status is text
priority :number         # Priority is a number
published :boolean       # Published is true/false
tags :array              # Tags is an array
metadata :object         # Metadata is an object
deletedAt :null          # DeletedAt is null

# Negated type checks
status !:number          # Status is NOT a number
tags !:string            # Tags is NOT a string (could be array)

Use cases:

• Data validation and cleanup
• Find incorrectly typed fields
• Normalize heterogeneous data

# Find notes where tags is a string instead of array
Condition: tags exists AND tags !:array
Action: SET tags ["{{fm:tags}}"]  # Convert string to array

ANY / ALL - Query Arrays of Objects

Check conditions across array items:

ANY - At least one item matches:

ANY projects WHERE status = "active"
ANY tasks WHERE priority > 7
ANY items WHERE tags contains "urgent"

ALL - Every item matches:

ALL projects WHERE verified = true
ALL tasks WHERE assignee exists
ALL items WHERE status != "deleted"

Nested queries (search within nested arrays):

# Find files where any project has any pending task
ANY projects WHERE ANY tasks WHERE status = "pending"

# Find files where all projects have completed tasks
ALL projects WHERE ALL tasks WHERE status = "done"

Real-world examples:

# File with project tracking
projects:
  - name: Alpha
    status: active
    priority: 8
  - name: Beta
    status: pending
    priority: 3

Conditions:

ANY projects WHERE status = "active"           # ✅ true (Alpha is active)
ALL projects WHERE status = "active"           # ❌ false (Beta is pending)
ANY projects WHERE priority > 5                # ✅ true (Alpha has 8)
ALL projects WHERE priority > 0                # ✅ true (both have priority)

Use with actions:

# Find files with any high-priority project, then tag them
Condition: ANY projects WHERE priority > 7
Action: FOR tags APPEND "high-priority-project"

Complex Criteria

Combine multiple operators for sophisticated file selection.

Operator Precedence

Understanding how conditions are evaluated is crucial for complex queries.

Default Precedence: AND before OR

Without parentheses, AND operators are evaluated before OR operators:

field1 = "a" OR field2 = "b" AND field3 = "c"

# This is parsed as:
field1 = "a" OR (field2 = "b" AND field3 = "c")

# NOT as:
(field1 = "a" OR field2 = "b") AND field3 = "c"

Example showing the difference:

# Condition: status = "draft" OR status = "review" AND priority > 5

# With default precedence (AND first):
# Matches: status="draft" (any priority)
# OR:      status="review" AND priority>5

# This would match:
status: draft, priority: 1  ✓ (draft with any priority)
status: review, priority: 8 ✓ (review with high priority)
status: review, priority: 3 ✗ (review with low priority)

Using Parentheses for Control

Use parentheses to explicitly control evaluation order:

Pattern: Group OR conditions

(status = "draft" OR status = "review") AND priority > 5

# Now both draft AND review must have priority > 5

Pattern: Complex multi-level grouping

((priority > 7 OR urgent = true) AND HAS deadline) OR status = "critical"

# Matches files that are:
# - (High priority OR urgent) AND have deadline
# OR
# - Have critical status

Pattern: Exclude multiple states

NOT (status = "archived" OR status = "deleted") AND HAS content

# Equivalent to:
status != "archived" AND status != "deleted" AND HAS content

Real-World Complex Conditions

Quality Gate Check:

(status = "draft" AND HAS tags AND tags.length >= 3) AND
(word_count > 500 AND word_count < 5000) AND
(HAS author AND author != "")

# All these must be true:
# 1. Draft status with at least 3 tags
# 2. Word count between 500 and 5000
# 3. Has non-empty author

Flexible State Matching:

(status = "pending" OR status = "review" OR status = "draft") AND
(HAS assignee OR HAS team) AND
NOT tags contains "blocked"

# Matches: Any of three states, with assignment, not blocked

Time-Based Filtering:

(created_date > "2025-01-01" AND created_date < "2025-12-31") OR
(updated_date > "{{today}}" OR review_date > "{{today}}")

# Matches files that are:
# - Created in 2025
# OR
# - Recently updated or reviewed

Nested Array Conditions:

(ANY tasks WHERE priority > 7 AND status = "pending") AND
(ALL reviewers WHERE approved = true) AND
HAS deadline AND deadline < "{{today}}"

# Complex check:
# - Has high-priority pending tasks
# - All reviewers approved
# - Has overdue deadline

Common Patterns

Pattern: Verify Completeness

HAS title AND title != "" AND
HAS content AND content.length > 100 AND
HAS tags AND tags :array AND tags.length > 0

# Ensures all required fields exist and have content

Pattern: Status Progression

(status = "review" AND ALL reviewers WHERE approved = true) OR
(status = "approved" AND HAS published_date)

# Ready to publish if:
# - In review with all approvals
# OR
# - Already approved with publish date

Pattern: Priority Escalation

(priority > 8 OR urgent = true OR deadline < "{{today}}") AND
status != "done" AND
NOT tags contains "blocked"

# High priority items that need attention

Pattern: Data Validation

(tags :array AND tags.length > 0) OR
(categories :array AND categories.length > 0) OR
HAS classification

# Has at least one categorization method

Debugging Complex Conditions

Start Simple, Add Complexity:

# Step 1: Basic condition
status = "draft"

# Step 2: Add one condition
status = "draft" AND HAS tags

# Step 3: Add more conditions
status = "draft" AND HAS tags AND tags.length >= 3

# Step 4: Add OR logic
(status = "draft" OR status = "review") AND HAS tags AND tags.length >= 3

# Step 5: Add exclusions
(status = "draft" OR status = "review") AND HAS tags AND tags.length >= 3 AND
NOT tags contains "archived"

Test Each Part:

# Break into sub-conditions and test separately:
Condition 1: status = "draft" OR status = "review"
Condition 2: HAS tags AND tags.length >= 3
Condition 3: NOT tags contains "archived"

# Then combine:
(Condition1) AND (Condition2) AND (Condition3)

Tips for Complex Conditions

1. Use Parentheses Liberally: Makes intent clear, prevents errors
2. Test on Small Sets: Verify logic before applying to many files
3. Break Down Complex Logic: Test parts separately
4. Use Type Checks: Verify data types before comparisons
5. Check Field Existence: Use HAS before accessing nested paths

Examples Summary

# Basic combination
status = "active" AND priority > 5

# OR with grouping
(status = "active" OR status = "pending") AND priority > 5

# Multiple levels
((priority > 7 OR urgent = true) AND HAS deadline) OR status = "critical"

# With NOT
NOT (status = "archived" OR status = "deleted") AND HAS content

# Complex nested
(status = "review" AND ALL reviewers WHERE approved = true) AND
(ANY tasks WHERE priority > 7) AND
NOT tags contains "blocked"

Field Types

Strings

title = "My Note"
status != ""

Numbers

count = 42
priority > 0

Booleans

published = true
archived != false

Arrays

tags contains "project"
categories = ["work", "urgent"]

Template Variables

Use template variables in condition values:

• - Current timestamp (ISO 8601)
• - Today's date (YYYY-MM-DD)

created_date < "{{now}}"
deadline <= "{{today}}"

Examples

See the Examples page for real-world use cases.