filter-structured

name	filter-structured
type	primitive
description	Filter Collection by field conditions (SQL WHERE)

Filter-Structured

INPUT CONTRACT

• target: Collection (variable or ID)
• where: SQL-like predicate string (e.g., "year > 2020", "score >= 0.5 AND year < 2025")
• out: Variable name

REQUIREMENTS:

• Collection MUST contain dict/JSON Notes
• WHERE clause uses field names (dot notation supported)
• Operators: >, <, >=, <=, ==, !=, AND, OR

NOT SUPPORTED:

• ❌ Note (must be Collection)
• ❌ Collection of arrays (must be dict Notes)
• ❌ Text parsing (use filter-semantic tool for semantic filtering)

OUTPUT

Returns Collection of Notes matching WHERE clause. Notes missing fields are excluded.

FAILURE SEMANTICS

Empty Collection = expected when:

• No Notes match predicate
• Type contract violated

Empty ≠ error — indicates no matches, not failure.

Actual failures: Invalid target type, malformed WHERE clause, or missing parameters.

REPRESENTATION INVARIANTS

• Note containing JSON array ≠ Collection
• Use split to convert array → Collection before filtering

ANTI-PATTERNS

❌ filter-structured(target=$note) → Must be Collection ❌ filter-structured(target=$coll_of_arrays) → Elements must be dicts ❌ filter-structured(target=$text_note) → Use filter-semantic for semantic filtering ❌ Treating empty result as error → Empty = no matches