feat: add cond/if/in to Query macro, document function pass-through (#32)

Query macro enrichment:
- `cond do ... end` compiles to SQL CASE WHEN ... THEN ... ELSE ... END
- `if(cond, do: x, else: y)` compiles to simple CASE WHEN
- `x in [1, 2, 3]` and `x in ^list` compile to SQL IN (...)

Documentation:
- Expanded Query moduledoc with all operators, conditionals, IN, and
  comprehensive DuckDB function examples by category (date, string,
  regex, list, struct, math, null, type)
- Updated getting-started guide with cond, if, in, DuckDB functions,
  and compute/1 in materialization section
- Updated README with cond/in examples and function pass-through note

52 query tests including happy path, adversarial (SQL injection strings,
null values, many branches), combined cond+in, and DuckDB function
pass-through verification.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cigrainger

README.md

@@ -65,7 +65,21 @@ min_amount = 500
 Dux.filter(df, amount > ^min_amount and status == "active")
 ```
 
-The `_with` variants accept raw DuckDB SQL for anything the macro doesn't cover:
+All DuckDB functions work inside expressions — `year()`, `lower()`, `coalesce()`, `regexp_matches()`, and [hundreds more](https://duckdb.org/docs/sql/functions/overview). `cond` maps to `CASE WHEN`, `in` maps to `IN`:
+
+```elixir
+Dux.mutate(df,
+  tier: cond do
+    amount > 1000 -> "gold"
+    amount > 100 -> "silver"
+    true -> "bronze"
+  end
+)
+
+Dux.filter(df, status in ["active", "pending"])
+```
+
+The `_with` variants accept raw DuckDB SQL for window functions and other constructs the macro doesn't cover:
 
 ```elixir
 Dux.mutate_with(df, rank: "ROW_NUMBER() OVER (PARTITION BY dept ORDER BY salary DESC)")

guides/getting-started.livemd

@@ -35,9 +35,18 @@ penguins
 
 ## Materialization
 
-Pipelines are lazy — nothing executes until you materialise. `compute/1`
-executes and returns a `%Dux{}` with the data. `to_rows/1` and `to_columns/1`
-extract raw Elixir data structures:
+Pipelines are lazy — nothing executes until you materialise:
+
+- `compute/1` — execute and return a `%Dux{}` with the data
+- `to_rows/1` — execute and return a list of maps
+- `to_columns/1` — execute and return a map of lists
+
+```elixir
+penguins
+|> Dux.filter(species == "Adelie")
+|> Dux.head(3)
+|> Dux.compute()
+```
 
 ```elixir
 penguins
@@ -113,6 +122,106 @@ penguins
 |> Dux.compute()
 ```
 
+## Conditional Expressions
+
+Elixir's `cond` compiles to SQL `CASE WHEN` — classify rows directly in your pipeline:
+
+```elixir
+penguins
+|> Dux.drop_nil([:body_mass_g])
+|> Dux.mutate(
+  size: cond do
+    body_mass_g > 5000 -> "large"
+    body_mass_g > 3500 -> "medium"
+    true -> "small"
+  end
+)
+|> Dux.group_by(:size)
+|> Dux.summarise(n: count(species))
+|> Dux.compute()
+```
+
+For simple two-branch logic, use `if/else`:
+
+```elixir
+penguins
+|> Dux.drop_nil([:body_mass_g])
+|> Dux.mutate(heavy: if(body_mass_g > 4500, do: "yes", else: "no"))
+|> Dux.group_by(:heavy)
+|> Dux.summarise(n: count(species))
+|> Dux.compute()
+```
+
+## Membership Tests
+
+Use `in` to filter by a set of values:
+
+```elixir
+penguins
+|> Dux.filter(species in ["Adelie", "Chinstrap"])
+|> Dux.group_by(:species)
+|> Dux.summarise(n: count(species))
+|> Dux.compute()
+```
+
+Works with interpolated lists too:
+
+```elixir
+target_islands = ["Biscoe", "Dream"]
+
+penguins
+|> Dux.filter(island in ^target_islands)
+|> Dux.group_by(:island)
+|> Dux.summarise(n: count(species))
+|> Dux.compute()
+```
+
+## Using DuckDB Functions
+
+All DuckDB functions work inside the query macro — they pass through as SQL
+function calls. Here are some useful ones:
+
+```elixir
+# String functions
+penguins
+|> Dux.mutate(
+  species_lower: lower(species),
+  first_char: left(species, 1)
+)
+|> Dux.select([:species, :species_lower, :first_char])
+|> Dux.distinct()
+|> Dux.compute()
+```
+
+```elixir
+# Math and rounding
+penguins
+|> Dux.drop_nil([:bill_length_mm, :bill_depth_mm])
+|> Dux.mutate(
+  bill_ratio: round(bill_length_mm / bill_depth_mm, 2),
+  log_mass: round(ln(body_mass_g), 2)
+)
+|> Dux.select([:species, :bill_ratio, :log_mass])
+|> Dux.head(5)
+|> Dux.compute()
+```
+
+```elixir
+# Null handling with coalesce
+penguins
+|> Dux.mutate(safe_sex: coalesce(sex, "unknown"))
+|> Dux.group_by(:safe_sex)
+|> Dux.summarise(n: count(species))
+|> Dux.compute()
+```
+
+> #### Any DuckDB function works {: .info}
+>
+> `lower()`, `upper()`, `trim()`, `year()`, `month()`, `date_diff()`,
+> `regexp_matches()`, `list_extract()`, `struct_extract()`, `coalesce()`,
+> `cast()`, and [hundreds more](https://duckdb.org/docs/sql/functions/overview).
+> If DuckDB has it, you can call it in a Dux expression.
+
 ## See the SQL
 
 Every pipeline compiles to SQL CTEs. Use `sql_preview/1` to inspect

lib/dux/query.ex

@@ -8,42 +8,122 @@ defmodule Dux.Query do
   Use `^` to interpolate Elixir variables — these become parameter bindings
   in the generated SQL, preventing SQL injection by construction.
 
-  ## Supported in queries
-
   Queries are used in `Dux.filter/2`, `Dux.mutate/2`, `Dux.summarise/2`,
   and `Dux.sort_by/2`.
 
   ## Operators
 
-  Comparison: `==`, `!=`, `>`, `>=`, `<`, `<=`
-  Arithmetic: `+`, `-`, `*`, `/`
-  Logical: `and`, `or`, `not`
-  String: `<>` (concatenation)
+  | Elixir | SQL |
+  |--------|-----|
+  | `==`, `!=`, `>`, `>=`, `<`, `<=` | `=`, `!=`, `>`, `>=`, `<`, `<=` |
+  | `+`, `-`, `*`, `/` | `+`, `-`, `*`, `/` |
+  | `and`, `or`, `not` | `AND`, `OR`, `NOT` |
+  | `<>` | `\|\|` (string concatenation) |
+  | `in [...]` | `IN (...)` |
 
-  ## Aggregation functions
+  ## Conditional expressions
+
+  Elixir's `cond` maps to SQL `CASE WHEN`:
+
+      Dux.mutate(df,
+        tier: cond do
+          amount > 1000 -> "gold"
+          amount > 100 -> "silver"
+          true -> "bronze"
+        end
+      )
+
+  Elixir's `if/else` for simple two-branch conditionals:
 
-  `sum(col)`, `mean(col)`, `min(col)`, `max(col)`, `count(col)`,
-  `count_distinct(col)`, `avg(col)`, `std(col)`, `variance(col)`
+      Dux.mutate(df, label: if(amount > 0, do: "positive", else: "negative"))
 
-  ## Other functions
+  ## Membership test
 
-  `col("name")` for columns with unusual names.
-  `cast(expr, type)` for type casting.
+  Elixir's `in` works with literal and pinned lists:
+
+      Dux.filter(df, status in ["active", "pending"])
+
+      allowed = ["active", "pending"]
+      Dux.filter(df, status in ^allowed)
 
   ## Interpolation
 
-  Use `^` to access variables defined outside the query:
+  Use `^` to interpolate Elixir values as parameter bindings:
 
       min_val = 10
       Dux.filter(df, x > ^min_val)
 
+  ## Aggregation functions
+
+  `sum`, `avg`/`mean`, `min`, `max`, `count`, `count_distinct`, `std`, `variance`
+
+  ## DuckDB functions
+
+  **All DuckDB functions work in queries.** Function calls pass through
+  to DuckDB unchanged. A few examples by category:
+
+  **Date/time:**
+
+      Dux.mutate(df, y: year(d), m: month(d), trunc: date_trunc("month", d))
+      Dux.mutate(df, age_days: date_diff("day", created_at, current_date()))
+
+  **String:**
+
+      Dux.mutate(df, low: lower(name), parts: string_split(path, "/"))
+      Dux.filter(df, starts_with(name, "A"))
+      Dux.mutate(df, clean: trim(replace(name, "  ", " ")))
+
+  **Regex:**
+
+      Dux.filter(df, regexp_matches(email, ".*@gmail\\\\.com"))
+      Dux.mutate(df, domain: regexp_extract(email, "@(.+)", 1))
+
+  **List/Array:**
+
+      Dux.mutate(df, first: list_extract(tags, 1), n: len(tags))
+
+  **Struct:**
+
+      Dux.mutate(df, city: struct_extract(address, "city"))
+
+  **Math:**
+
+      Dux.mutate(df, log_amt: ln(amount), pct: round(ratio * 100, 2))
+
+  **Null handling:**
+
+      Dux.mutate(df, safe: coalesce(nullable_col, 0))
+
+  **Type casting:**
+
+      Dux.mutate(df, as_text: cast(id, "VARCHAR"), as_int: cast(amount, "INTEGER"))
+
+  For the full list, see the
+  [DuckDB Functions reference](https://duckdb.org/docs/sql/functions/overview).
+
+  For anything the macro doesn't support (window functions, subqueries),
+  use the `_with` variants (`mutate_with/2`, `filter_with/2`) which accept
+  raw DuckDB SQL strings.
+
+  ## Column references
+
+  `col("name")` for columns with spaces or special characters:
+
+      Dux.filter(df, col("Total Amount") > 100)
+
   ## Examples
 
       # Filter
       Dux.filter(df, age > 18 and status == "active")
 
-      # Mutate
-      Dux.mutate(df, revenue: price * quantity, tax: price * ^tax_rate)
+      # Mutate with conditional
+      Dux.mutate(df,
+        revenue: price * quantity,
+        tier: cond do
+          price > 100 -> "premium"
+          true -> "standard"
+        end
+      )
 
       # Summarise
       Dux.summarise(df, total: sum(amount), n: count(id))
@@ -137,6 +217,49 @@ defmodule Dux.Query do
     {{:negate, ast}, pins}
   end
 
+  # cond → CASE WHEN ... THEN ... ELSE ... END
+  defp traverse({:cond, _meta, [[do: clauses]]}, pins) do
+    {pairs, else_expr, pins} =
+      Enum.reduce(clauses, {[], nil, pins}, fn {:->, _m, [[condition], result]},
+                                               {pairs, _else, pins} ->
+        {cond_ast, pins} = traverse(condition, pins)
+        {result_ast, pins} = traverse(result, pins)
+
+        case cond_ast do
+          {:lit, true} ->
+            # `true -> expr` becomes the ELSE branch
+            {pairs, result_ast, pins}
+
+          _ ->
+            {pairs ++ [{cond_ast, result_ast}], nil, pins}
+        end
+      end)
+
+    {{:case_when, pairs, else_expr}, pins}
+  end
+
+  # if/else → CASE WHEN cond THEN then_expr ELSE else_expr END
+  defp traverse({:if, _meta, [condition, [do: then_expr, else: else_expr]]}, pins) do
+    {cond_ast, pins} = traverse(condition, pins)
+    {then_ast, pins} = traverse(then_expr, pins)
+    {else_ast, pins} = traverse(else_expr, pins)
+    {{:case_when, [{cond_ast, then_ast}], else_ast}, pins}
+  end
+
+  # if without else → CASE WHEN cond THEN then_expr ELSE NULL END
+  defp traverse({:if, _meta, [condition, [do: then_expr]]}, pins) do
+    {cond_ast, pins} = traverse(condition, pins)
+    {then_ast, pins} = traverse(then_expr, pins)
+    {{:case_when, [{cond_ast, then_ast}], {:lit, nil}}, pins}
+  end
+
+  # in operator → SQL IN
+  defp traverse({:in, _meta, [left, right]}, pins) do
+    {l_ast, pins} = traverse(left, pins)
+    {r_ast, pins} = traverse(right, pins)
+    {{:in, l_ast, r_ast}, pins}
+  end
+
   # String concatenation: <>
   defp traverse({:<>, _meta, [left, right]}, pins) do
     {l_ast, pins} = traverse(left, pins)

lib/dux/query/compiler.ex

@@ -139,6 +139,57 @@ defmodule Dux.Query.Compiler do
     {"#{sql_name}(#{Enum.join(arg_sqls, ", ")})", all_params, idx}
   end
 
+  # --- CASE WHEN ---
+
+  defp compile({:case_when, pairs, else_expr}, pins, idx) do
+    {when_clauses, all_params, idx} =
+      Enum.reduce(pairs, {[], [], idx}, fn {condition, result}, {clauses, params, idx} ->
+        {cond_sql, cond_params, idx} = compile(condition, pins, idx)
+        {result_sql, result_params, idx} = compile(result, pins, idx)
+        clause = "WHEN #{cond_sql} THEN #{result_sql}"
+        {clauses ++ [clause], params ++ cond_params ++ result_params, idx}
+      end)
+
+    {else_clause, else_params, idx} =
+      case else_expr do
+        nil ->
+          {"", [], idx}
+
+        expr ->
+          {sql, params, idx} = compile(expr, pins, idx)
+          {" ELSE #{sql}", params, idx}
+      end
+
+    sql = "(CASE #{Enum.join(when_clauses, " ")}#{else_clause} END)"
+    {sql, all_params ++ else_params, idx}
+  end
+
+  # --- IN operator ---
+
+  defp compile({:in, left, {:pin, pin_idx}}, pins, idx) do
+    {l_sql, l_params, idx} = compile(left, pins, idx)
+    values = Enum.at(pins, pin_idx)
+    # Pinned list — expand to individual parameter bindings
+    {placeholders, idx} =
+      Enum.reduce(values, {[], idx}, fn _v, {phs, idx} ->
+        {phs ++ ["$#{idx + 1}"], idx + 1}
+      end)
+
+    {"(#{l_sql} IN (#{Enum.join(placeholders, ", ")}))", l_params ++ values, idx}
+  end
+
+  defp compile({:in, left, right}, pins, idx) when is_list(right) do
+    {l_sql, l_params, idx} = compile(left, pins, idx)
+
+    {val_sqls, val_params, idx} =
+      Enum.reduce(right, {[], [], idx}, fn item, {sqls, params, idx} ->
+        {sql, new_params, idx} = compile(item, pins, idx)
+        {sqls ++ [sql], params ++ new_params, idx}
+      end)
+
+    {"(#{l_sql} IN (#{Enum.join(val_sqls, ", ")}))", l_params ++ val_params, idx}
+  end
+
   # --- Sort direction markers ---
 
   defp compile({:asc, expr}, pins, idx) do