filter-structured_skill

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.