Changelog

v0.7.0

Added

• derived_from on projected columns. Each column returned by build_pipe/2 now also carries derived_from: nil for plain projections, and for computed columns %{function: name, fields: paths} — the outermost function or aggregation and every source path it reads, followed through nested functions and earlier stages. count() reads no paths. Callers that previously matched the column maps exactly need to account for the new key.

v0.6.1

Changed

• date(column) comparisons against constant dates use the column's index. When date(col) or date(col, zone) is compared with a literal date, a bound Date, or a literal_transform date range (including BETWEEN), the builder compares the raw column against day-start instants (midnight in the session zone, or in zone) instead of casting every row. Results are identical; comparisons against other columns, and date() on a column that is already a date, compile as before.

v0.6.0

Added

• Coercion and date-part functions: date(value), date(datetime, zone), at_zone(datetime, zone), text, integer, number, year, month, day, weekday (ISO, Monday = 1), hour, and days_between(from, to). Each carries a result type, so the opposite operand of a comparison is cast to match (date(created_at) == {{day}} binds day as a date) and projected columns report it. Zones are IANA names, validated for shape and inlined with Ecto's constant/1, so zoned expressions group correctly; plain timestamp columns are read in the session TimeZone.

Changed

• Requires Ecto ~> 3.13 (for constant/1).

v0.5.2

Added

• Output columns report their provenance. Each entry build_pipe/2 returns in columns now carries field: the source path a plain projection or breakout reads (["customer", "region"] for customer.region), carried through later stages that re-project it by name, and nil for anything computed (functions, aggregations). Callers can map an output column back to its catalog entry — types, labels, descriptions — without re-parsing the query.

v0.5.1

Fixed

• Table names may contain hyphens. A pipe source segment previously had to be a bare unquoted SQL identifier, so a schema-per-tenant layout that names schemas after UUIDs — client_559de6a3-0cc8-4813-a9be-9c31a39ab47d.controls — failed to parse at the first hyphen. Table references only ever appear in the source position, where there is no arithmetic for a - to belong to, so hyphens are unambiguous there. A source must still start like an identifier, and aliases, column paths, and function names are unchanged.

v0.5.0

One release, two headline features: {{name}} parameters (with [[optional]] groups and the literal_transform: hook) for the existing filter API, and the full pipe language — the staged query language from docs/pipe-language.md (source + filter/select/group/sort/limit/ offset stages, staged compilation, @slug external references, positioned validation errors). The pipe language was originally slated for v0.6.0 and was folded into this unpublished release instead of shipping two releases in one day.

Added — the pipe language

• EctoQueryParser.parse_pipe/1 and EctoQueryParser.build_pipe/2 — parse and compile staged pipe queries:

  orders
  | filter status == "paid" AND created_at >= "last month"
  | group customer.region { total = sum(amount), n = count() }
  | sort -total
  | limit 10

  A query is a source plus |-separated stages (whitespace/newlines around | insignificant; a bare source is valid). parse_pipe/1 returns an %EctoQueryParser.Pipe.Query{} exposing the :source so callers can validate the referenced table against their catalog before building; build_pipe/2 accepts the text or the parsed struct plus the existing allowed_fields: / params: / literal_transform: options and the new resolve_source:.

• Stages.

  • filter <expr> — the existing filter grammar verbatim (operators, functions, association paths with JOIN/EXISTS, JSONB paths, {{params}}, [[optional]] groups). Multiple filter stages allowed.
  • select col [, col ...] — identifiers (association paths, singular-only) or alias = FUNC(...) with the existing function set; restricts the output shape for later stages.
  • group [breakouts] { alias = agg(...), ... } — breakouts are identifiers, function applications (ROUND_* temporal bucketing), or alias = FUNC(...); un-aliased function breakouts get a derived, referenceable name (round_month_created_at). Aggregations: count(), count(col), count_distinct(col), sum(col), avg(col), min(col), max(col) — every aggregation aliased, aliases must not collide with each other or breakout names. group { ... } with no breakouts is a single-row summary. Output shape = breakouts then aliases.
  • sort key [, key ...] — -key descending; after a group, keys refer to the grouped output including aliases. A later sort replaces an earlier one.
  • limit N / offset N — non-negative integer literals only, at most one of each; row capping stays the caller's job.

• Staged compilation. Stages fold onto one Ecto query; the first column-referencing stage after a projection (or after limit/offset on a projected level) wraps the accumulated query in a subquery, so filter after group is HAVING semantics with no special case. Consecutive same-shape stages share a query level. Output field specs flow stage to stage (breakouts keep the underlying field type, sum/min/max keep their argument's, count* are :integer), so coercion and literal_transform: keep working over grouped output.

• Positional output columns (atom safety). Aliases never become atoms: projections select into the fixed key set :c0..:c63 (max 64 columns per stage) and build_pipe/2 returns {:ok, query, columns} where columns is the ordered %{name: "total", key: :c1} rename mapping (nil when no projection stage ran). A hostile flood of unique alias/table/slug/column names cannot grow the atom table — covered by regression tests.

• @slug external references (@monthly-revenue; slugs [a-z0-9][a-z0-9-_]*) resolve through the new resolve_source: option: fn slug -> {:ok, queryable, fields} | {:error, message} end. The queryable is inlined as a subquery source and fields (an allowed_fields-format spec of its output) validates and types the stages that follow. Missing resolver, resolver errors, and off-contract returns are clear build errors carrying the source's position.

• Positioned validation errors — new EctoQueryParser.ValidationError exception struct with message, line/column/byte_offset, stage, and stage_index. Identifiers, aliases, and stage keywords carry source positions through the pipe AST, so unknown columns in select/group/sort, alias collisions, plural associations outside filters, unresolvable @refs, and duplicate limit/offset stages point at the offending token. Boundary: errors arising inside a filter stage's boolean expression keep the plain {:error, binary} shape (prefixed with "in filter stage N: ") — the filter grammar's AST carries no per-token positions.

• EctoQueryParser.parameters/1 accepts pipe queries (text or parsed struct), collecting {{name}} parameters across all filter stages with the same required semantics.

Added — parameters and literals

• {{name}} parameters. Placeholders are valid anywhere a literal may appear (right side of comparisons, list elements, function arguments, BETWEEN bounds); names match [A-Za-z_][A-Za-z0-9_]* and whitespace inside the braces is tolerated. Values bind at build time via the new params: %{"name" => value} option on EctoQueryParser.apply/3 and Builder.build/2, and behave exactly like inline literals: same type coercion against the field's type, always bound as prepared-statement parameters. Values without a literal syntax (Date, Decimal, ...) can be passed directly. An unbound parameter (missing key or nil) is a build error: {:error, "missing required parameter: name"}. Parameter names stay strings end to end — no atoms.
• [[ ... ]] optional groups. A bracketed group carries its AND/OR connector inside the brackets and attaches to the surrounding boolean chain at that connector's precedence level (status == "x" [[AND created_at >= {{start}}]]); a connector-less [[expr]] may stand as the whole filter (degenerating to WHERE TRUE when pruned). If every {{param}} in a group is bound, the group participates as if the brackets were absent; if any is unbound, the whole group is pruned before building. Groups with no parameters are always included. Groups do not nest; unmatched or nested brackets are ParseErrors with positions. Pruning runs after parse and before the EXISTS rewriter, so groups compose with plural-association predicates (merging into the same EXISTS) and NOT.
• EctoQueryParser.parameters/1 — parameter discovery. Returns {:ok, [%{name: "status", required: true}, ...]} in order of first appearance; required is false iff every occurrence of the name sits inside optional groups. Parse failures return the usual {:error, %ParseError{}}.
• literal_transform: build option — a fun(ecto_type, raw_string) hook called for string literals (and bound string parameter values) resolved against a typed field, before the built-in coercion — on plain fields, association-path leaves (including inside EXISTS), BETWEEN bounds, IN elements, includes, and LIKE/ILIKE patterns. Returns:
  • :default — today's behavior (coercion + type/2 wrap);
  • {:ok, term} — replace the value, bound as a plain pin with no type/2 wrap (the transform owns the type);
  • {:range, {lo, hi}} — the literal denotes an inclusive range, compiled per operator: == → >= lo AND <= hi, != → its negation, >= → >= lo, > → > hi, <= → <= hi, < → < lo; BETWEEN bounds resolve independently (low takes lo, high takes hi); a literal on the left flips the operator first. {:range, _} for any other operator (IN elements, LIKE, includes) is a build error with a clear message.

Changed

• ROUND_* functions now inline their DATE_TRUNC unit as a SQL literal (DATE_TRUNC('month', ...)) instead of binding it as a parameter. The unit comes from a fixed internal map (never from input), and inlining keeps the expression textually identical wherever it repeats — required for grouped SELECT/GROUP BY expressions to match under Postgres.

Fixed

• Building a list containing a non-literal (e.g. an identifier) now returns {:error, "lists may only contain literal values, ..."} instead of raising a FunctionClauseError.

v0.4.0

Security

• Fixed an atom-exhaustion vulnerability in dotted-identifier resolution. resolve_dotted_identifier/2 and the JSON-path resolver called String.to_atom/1 on raw input before any allowlist check, so a hostile stream of unique dotted identifiers (a.b1 == 1, a.b2 == 1, …) could grow the BEAM atom table without bound and crash the node. Since this library's entire purpose is filtering by untrusted input, treat this as a mandatory upgrade. No code path converts input to atoms anymore:
  • Allowlist (:allowed_fields) checks now compare strings.
  • Association segments and leaf fields resolve via String.to_existing_atom/1; unknown names return the usual "unknown field: ..." / "unknown association: ..." errors.
  • JSON path segments stay plain strings all the way into json_extract_path/2 — they never touch the atom table.
  • Regression tests assert the atom count stays flat under hostile input.

Changed (BREAKING)

• Parse failures now return {:error, %EctoQueryParser.ParseError{}} instead of {:error, binary}. The struct is an Exception carrying message, line (1-based), column (1-based), byte_offset, and rest (the unconsumed input, truncated) — enough to power editor diagnostics. Exception.message/1 renders a one-liner including the position. This applies to EctoQueryParser.parse/1 and propagates through EctoQueryParser.apply/3. Code matching {:error, reason} when is_binary(reason) on parse failures must be updated; builder/validation errors (unknown field, field not allowed, unknown function, …) keep their {:error, binary} shape, since no source position is known at that stage.

Added

• Strict comparison operators > and < (with the same literal type coercion as >= / <=).
• NOT — unary logical negation: NOT expr, NOT (a OR b). Precedence is NOT > AND > OR. Accepts NOT / not, like the other keywords. Negating a plural-association predicate now produces NOT EXISTS, lifting the v0.3.0 limitation ("posts with no matching comments" works).
• IS NULL / IS NOT NULL — postfix on identifiers, association paths, JSON paths, and function expressions; compiles to is_nil/1 / not is_nil/1.
• IN — list membership: age IN [18, 21], status in ["a", "b"]. List elements are type-coerced against the field's type the same way == coerces its literal.
• BETWEEN — field BETWEEN low AND high compiles to field >= low and field <= high, with both bounds coerced to the field's type. The inner AND binds to BETWEEN, not the logical connector.
• All new operators work on plain fields, association paths (respecting the JOIN vs EXISTS split for plural associations), and inside parentheses.
• Parse-failure messages are now labeled and concise instead of NimbleParsec's exhaustive expected-token dump.

v0.3.1

Fixed

• many_to_many filters with :join_prefix crashed with FunctionClauseError in Ecto.Queryable.Tuple.to_query/1. The EXISTS subquery built the inner-join source as a {prefix, table} string tuple and pinned it into the join macro; at runtime that falls through Ecto.Queryable.to_query/1 which only accepts {string, atom} tuples. The prefix is now passed via join/5's :prefix keyword option, the same pattern used for prefixed belongs-to joins.

v0.3.0

Added

• has_many and many_to_many relationship support. Plural-side filters now compile to correlated EXISTS subqueries instead of LEFT JOINs, avoiding the row-duplication that previously corrupted counts and ORDER BY / LIMIT on schema-based has-many filters.
• New schemaless allowed_fields tuple shapes peer with the existing {:assoc, ...}:
  • {:belongs_to, table:, owner_key:, related_key:, fields:, prefix:} — alias for {:assoc, ...}.
  • {:has_many, table:, owner_key:, related_key:, fields:, prefix:} — emits EXISTS (SELECT 1 FROM table WHERE related_key = parent.owner_key …).
  • {:many_to_many, table:, join_through:, join_owner_key:, join_related_key:, owner_key:, related_key:, fields:, prefix:, join_prefix:} — emits EXISTS through the join table.
• Schema-mode association cardinality is auto-detected from __schema__(:association, name). belongs_to and has_one keep producing LEFT JOIN; has_many and many_to_many switch to EXISTS.
• §4-style grouping: when multiple predicates filter the same plural alias under the same boolean connector, they collapse into one EXISTS. AND on comments.body and comments.spam produces a single subquery whose WHERE clause combines both predicates; OR similarly OR-s them inside one EXISTS. Predicates on different aliases stay in separate EXISTS clauses.
• :prefix option on belongs_to, has_many, and many_to_many tuples (also :join_prefix on many_to_many) flows through to the LEFT JOIN source or EXISTS subquery's FROM / JOIN. This eliminates the need for downstream JoinExpr.prefix patching when using schema prefixes for multi-tenancy.

Changed

• Schema-mode has_many filtering previously emitted a LEFT JOIN that silently duplicated parent rows for each match. It now emits an EXISTS subquery and never duplicates. This is a deliberate fix; users who were applying DISTINCT externally to compensate can remove it.
• EctoQueryParser.apply/3 now normalizes the queryable to an %Ecto.Query{} and names the source binding (as: :__eqp_source) if the user hasn't named it. This lets the EXISTS subquery's parent_as correlation reference the outer source. A user-supplied as: on the source is preserved.

Limitations (v1)

• Plural associations must be the first segment of a dotted path: comments.author.name works, but author.comments.body returns an error. This restriction may be lifted in a follow-up.
• NOT EXISTS filters ("posts with no comments") are not yet supported — they require parser-level negation, which is a separate change.

v0.2.0

• Automatic literal type coercion in comparisons. When a literal is compared against a typed field (e.g., performed_on >= "2026-05-20" where performed_on is a :date), the literal is now wrapped with type/2 so Ecto and the database driver cast it to the column's type. Previously this could fail in PostgreSQL with errors like operator does not exist: date >= text.
• Coercion sources its type information from the schema (__schema__(:type, _)), from the keyword form of :allowed_fields, and by walking association paths to the leaf field. Works for ==, !=, >=, <=, and includes in both operand orders.
• Coercion is skipped when the literal's natural type already matches the field (e.g., string-vs-string, integer-vs-integer), so existing queries are not affected.

v0.1.0

• Initial release
• Query language parser with support for strings, integers, floats, booleans, and lists
• Comparison operators: ==, !=, >=, <=
• Text operators: contains, like, ilike, search
• Array operator: includes
• Logical operators: AND, OR, parenthesized grouping
• String functions: UPPER, LOWER, TRIM, LENGTH, LEFT, RIGHT, SUBSTRING, CONCAT, REPLACE, COALESCE
• Math functions: ABS, FLOOR, CEIL
• Date/time functions: NOW(), ROUND_SECOND through ROUND_YEAR, ADD_INTERVAL, SUB_INTERVAL
• Automatic left joins for dotted association paths (e.g., author.name)
• JSONB column access for :map fields (e.g., metadata.key)
• Schemaless query support with association definitions in allowed_fields
• Field allowlisting via :allowed_fields option