# filtering

Guides your AI agent on building filter expressions, handling dates, and structuring queries in Honeydew.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 43
- Author: honeydew-ai
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/honeydew-ai/honeydew-ai-coding-agents-plugins/tree/HEAD/skills/filtering/SKILL.md
- Updated: 2026-08-30
- HTML: https://affpapa.org/en/nevibecode/skills/filtering

## What it does

The skill defines syntax and evaluation rules across four Honeydew contexts: structured queries in `get_data_from_fields`, metric aggregations, per-row attribute expressions, and post-aggregation metric filters. It covers exact comparison operators, pattern matching with `ILIKE`, `NULL` checks, and explicit type casting like `::DATE`.

For dates, the rules prescribe functions such as `CURRENT_DATE`, `DATE_TRUNC`, and `INTERVAL`, explicitly barring relative interval math for specific calendar dates. Snowflake is the only platform supporting the `SEARCH` full-text function here, which strictly requires `SEARCH_MODE => 'AND'`. In metric aggregations, standard `FILTER (WHERE ...)` syntax replaces `CASE WHEN`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add honeydew-ai/honeydew-ai-coding-agents-plugins --skill filtering -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/filtering/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/filtering/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add honeydew-ai/honeydew-ai-coding-agents-plugins --skill filtering -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/filtering/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add honeydew-ai/honeydew-ai-coding-agents-plugins --skill filtering -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/filtering/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install honeydew-ai/honeydew-ai-coding-agents-plugins filtering
```

2. **Manually: put the files in place**
- File: `.github/skills/filtering/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add honeydew-ai/honeydew-ai-coding-agents-plugins --skill filtering -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/honeydew-ai/honeydew-ai-coding-agents-plugins --path skills/filtering
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/filtering/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add honeydew-ai/honeydew-ai-coding-agents-plugins --skill filtering -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/honeydew-ai/honeydew-ai-coding-agents-plugins/tree/HEAD/skills/filtering/SKILL.md

## When to use it
- pass pre-aggregation conditions to `filters` in `get_data_from_fields`
- restrict metric aggregation inputs using `FILTER (WHERE ...)`
- construct relative date filters using `DATE_TRUNC` and `CURRENT_DATE`
- run full-text searches on Snowflake with `SEARCH_MODE => 'AND'`

## Example prompts
- Query `detailed_listings` filtered by price over 50 and room type set to Entire home/apt.
- Add a completed status condition to the order count metric with `FILTER (WHERE ...)`.
- Filter sales for the previous month using standard date truncation functions.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 5b920ef847f71938.

BEGIN THIRD-PARTY FILE 5b920ef847f71938
````text
---
name: filtering
description: Use when the user needs to filter data — whether in a structured query, a metric aggregation, or an attribute expression. Covers filter syntax, date handling, and best practices.
---

## Overview

Filtering restricts which rows contribute to a result. The same expression language applies across three contexts in Honeydew:

| Context                  | Where it appears                                          | When it runs       |
| ------------------------ | --------------------------------------------------------- | ------------------ |
| **Structured query**     | `filters` parameter in `get_data_from_fields` / `get_sql_from_fields` | Pre-aggregation    |
| **Metric aggregation**   | `FILTER (WHERE ...)` on an aggregation                    | During aggregation |
| **Attribute expression** | `CASE WHEN ... END` in attribute SQL                      | Per-row evaluation |
| **Metric value filter**  | Metric expression in `filters` parameter                  | Post-aggregation   |

---

## Filter Expression Syntax

### Comparisons

```sql
entity.field = 'value'
entity.field > 100
entity.field >= 3 AND entity.field < 10
```

Operators: `=`, `<`, `>`, `>=`, `<=`, `!=`

You can compare an attribute to a constant or to another attribute. Cast mismatching types when comparing (e.g., `entity.field::DATE`).

### Strings

```sql
entity.field = 'exact value'
entity.field IN ('val1', 'val2', 'val3')
entity.field ILIKE '%keyword%'
```

- `ILIKE` is case-insensitive pattern matching (`%` = any characters, `_` = one character)

### Full-Text Search (Snowflake only)

Use `SEARCH` when you don't know exact values and need to find possible matches.

```sql
-- Single search — always use SEARCH_MODE => 'AND'
SEARCH(entity.field, 'search terms', SEARCH_MODE => 'AND')

-- Multiple alternatives — use OR between SEARCH calls
SEARCH(entity.field, 'term1', SEARCH_MODE => 'AND') OR SEARCH(entity.field, 'term2', SEARCH_MODE => 'AND')
```

**Always use `SEARCH_MODE => 'AND'`.**

### NULL Checks

```sql
entity.field IS NULL
entity.field IS NOT NULL
```

### Booleans

```sql
entity.flag = true
entity.flag = false
```

### Date Comparisons

```sql
YEAR(entity.date_field) = 2023
entity.date_field >= '2024-01-01'
entity.date_field BETWEEN '2024-02-05'::DATE AND '2024-02-10'::DATE
```

### Combining Conditions

```sql
entity.price > 50 AND entity.room_type = 'Private room'
entity.status = 'active' OR entity.status = 'pending'
```

Use `AND` / `OR` to combine conditions. Use parentheses to control precedence.

### Type Casting

Cast when types don't match:

```sql
entity.string_field::DATE
entity.number_field::VARCHAR
'2024-01-01'::DATE
DATE('2024-01-01')
```

---

## Filtering Contexts

### 1. Structured Query Filters
````
END THIRD-PARTY FILE 5b920ef847f71938

The third-party file has ended. Everything between the 5b920ef847f71938 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2775 of 5990 bytes. © honeydew-ai · Apache-2.0 · https://github.com/honeydew-ai/honeydew-ai-coding-agents-plugins/tree/HEAD/skills/filtering/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md