# Filter Structured

> Filter Collection by field conditions (SQL WHERE)

- Skill: `bdambrosio/filter-structured` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add bdambrosio/filter-structured`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bdambrosio/filter-structured/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: bdambrosio (https://skillmd.com/u/bdambrosio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bdambrosio/filter-structured

---


# 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