# SQL grammar

The `q` parameter on `/scan` and the `q` field on `/webhooks` both accept a SQL WHERE clause. Identifiers are flag names (booleans) or column names (numerics, strings, dates) from the schema.

## What we don't accept

- No subqueries or joins. The query filters a single row of the ticker table.
- No string functions (LIKE, ILIKE). Use IN with a finite set instead.
- No date arithmetic beyond what flags already expose (e.g. `earnings_this_week`).
- No CASE expressions or computed columns.

## Examples

**Bullish breakouts on volume** — Stocks breaking out today on at least 2× their normal volume.

```
breakout AND high_volume_alert
```

**Small-cap gappers, avoiding earnings noise** — Small caps gapping up 3% on heavy volume, with no earnings announcement this week.

```
gap_up AND small_cap AND high_volume_alert AND NOT earnings_this_week
```

**Oversold tech with healthy fundamentals** — Oversold technology names that are still profitable.

```
rsi_oversold AND sector = 'Technology' AND pe_ratio BETWEEN 5 AND 30
```

**New 52-week highs with momentum** — Stocks making fresh 52-week highs with strong upward momentum.

```
at_52w_high AND momentum_strong_up
```

**Crypto breakouts** — Cryptocurrencies breaking above their 20-day high.

```
breaking_above_20d_high
```

**Mega-cap consolidation** — Mega-cap stocks coiling for a move: tight Bollinger bands, low volatility.

```
market_cap > 200000000000 AND atr_percent < 1.5
```

**Sector rotation candidates** — Healthcare and energy names crossing above their 50-day average.

```
sector IN ('Healthcare', 'Energy') AND above_sma_50 AND NOT in_downtrend
```

**Macro-conditioned setup (qualified context tickers)** — RSI-oversold names, but only when the VIX is under 20 and the S&P 500 is above its 50-day average.

```
rsi_oversold AND vix.close < 20 AND spy.close > spy.sma_50
```

**Sector-relative breakout** — Tech breakouts that are also outpacing the tech sector ETF on the same day.

```
breakout AND sector = 'Technology' AND day_change_pct > xlk.day_change_pct
```

## URL encoding

When sending the query as a URL parameter, encode it. Most HTTP clients do this automatically. Spaces become `%20`, `>` becomes `%3E`, single quotes become `%27`. When in doubt, send the query in a JSON body via `POST /v2/scan`; no encoding needed.