playbooks

home / skills / bdambrosio / cognitive_workbench / filter-structured

filter-structured skill

/src/primitives/filter-structured

This skill filters a collection of dict notes by a SQL-like WHERE predicate, returning only matching entries.

npx playbooks add skill bdambrosio/cognitive_workbench --skill filter-structured

Review the files below or copy the command above to add this skill to your agents.

Files (1)
Skill.md
1.4 KB
---
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

Overview

This skill filters a collection of JSON/dict Notes using SQL-like WHERE predicates. It returns a new collection containing only Notes that satisfy the field conditions, excluding items missing required fields. Empty collections indicate no matches, not an error.

How this skill works

You pass a target Collection, a SQL-like where string, and an output variable name. The skill evaluates the predicate against each Note (dict) using supported operators and logical connectors and includes only Notes that have the referenced fields. Notes missing any referenced field are excluded from results.

When to use it

  • You need deterministic, field-level filtering of structured Notes.
  • You have a Collection of dict/JSON Notes and need SQL-like predicates.
  • You want fast exact-match or range filtering instead of semantic or text-based searches.
  • You need to chain this filter in a data-processing pipeline that expects Collections.

Best practices

  • Ensure the target is a Collection of dict/JSON Notes — not a single Note or a Collection of arrays.
  • Use dot notation for nested fields (e.g., metadata.author == 'Alice').
  • Prefer supported operators: >, <, >=, <=, ==, != and logical AND/OR.
  • Pre-split any JSON arrays into a Collection before filtering.
  • Treat an empty returned Collection as a valid no-match result, not an error.

Example use cases

  • Select recent records: where="year > 2020" to keep Notes with year after 2020.
  • Filter by score and date: where="score >= 0.5 AND year < 2025".
  • Find items with a specific nested field value using dot notation, e.g., metadata.status == 'approved'.
  • Combine multiple conditions with OR to broaden matches, e.g., category == 'news' OR category == 'blog'.
  • Preprocess a dataset: split arrays into a Collection, then filter to produce a cleaned subset.

FAQ

What happens if a Note is missing a field referenced in the WHERE clause?

Notes missing any referenced field are excluded from the result. Missing fields cause no match rather than an error.

Is semantic or text parsing supported in the WHERE clause?

No. This tool performs structured field comparisons only. For semantic or text-based filtering, use a dedicated semantic filter tool.