Default filter implementations for Patterns.Queryable modules.

apply_filter/2 turns common filter tuples into Ecto query expressions so a Patterns.Queryable module can focus on custom filters and delegate the rest.

Query Modifiers

Query modifiers affect only the top-level query. They are ignored inside association filters.

Supported modifiers are:

• {:distinct, value}
• {:limit, value}
• {:offset, value}
• {:preload, value}
• {:select, value}

Modifier values are forwarded to Ecto's query DSL, so Ecto syntax like {:preload, :comments}, {:preload, [comments: :post]}, and {:distinct, true} is supported. Atom selects are treated as fields on the current binding, so {:select, :id} selects the current binding's id field. Non-atom selects are passed through to Ecto as values. Distinct values are forwarded to Ecto; use {:distinct, true} as the portable parent-deduplication form for association filters.

Modifier behavior is delegated to Ecto and the configured adapter. SQL shape and support can differ between adapters such as ecto_sqlite3 and PostgreSQL, especially for non-boolean distinct values and complex preloads.

Field Comparators

Field comparators apply predicates to the current binding.

Supported comparators are:

• {field, value} and {field, {:eq, value}}
• {field, nil} and {field, {:eq, nil}}
• {field, [value]} and {field, {:in, [value]}}
• {field, %Regex{}} and {field, {:like, %Regex{}}}
• {field, {:not, value}}
• {field, {:not, nil}}
• {field, {:not, [value]}} and {field, {:not_in, [value]}}
• {field, {:not, %Regex{}}} and {field, {:not_like, %Regex{}}}
• {field, {:gt, value}}
• {field, {:gte, value}}
• {field, {:lt, value}}
• {field, {:lte, value}}
• {field, {:like, pattern}}
• {field, {:not_like, pattern}}

Unsupported comparator tuples raise ArgumentError instead of silently becoming equality comparisons against the tuple value.

Regex Values

The i regex option lower-cases the field and generated LIKE pattern. Other regex options raise ArgumentError.

Matching semantics are still delegated to the database adapter and collation. For example, plain SQL LIKE case-sensitivity can differ between SQLite and PostgreSQL.

Literal % and _ are rejected in regex shorthand because they are SQL LIKE wildcards. Escaped regex syntax is not supported.

Regex syntax that cannot be represented by this simple conversion raises ArgumentError.

Association Comparators

Association comparators use {field, filters} where filters is a map or keyword-shaped list and field is an Ecto association.

Empty filters like {:comments, []} and {:comments, %{}} still join the association. When Patterns.Queryable adds a new inner join, they match parents with at least one associated row. When an existing named binding is reused, that binding's join semantics are preserved.

Treating map and keyword values as association filters is an implementation detail. Future versions may support map equality for field types that can encode and compare maps directly, such as PostgreSQL jsonb fields.

Association filters require a schema-backed query source because they inspect association metadata from the current scoped binding. Raw string sources and subquery sources cannot use association filters.

Join generation and association metadata are delegated to Ecto. Adapter SQL output may differ, but the filter semantics are based on Ecto's assoc/2 join behavior.

Nested association filters are resolved from the current scoped binding, so {:comments, [post: [title: "Hello"]]} filters :post as an association of the joined :comments binding.

Association filters use Ecto's assoc/2 join syntax and keep normal join semantics. For has_many and many_to_many associations, one parent row is returned for each matching associated row. Pass {:distinct, true} when parent row uniqueness matters.

When the associated schema exports query/2, nested filters are delegated to that function against the joined association binding. Otherwise, each nested filter is applied directly to the joined association binding.

Binding resolution uses Patterns.Queryable.DSL.binding_schema/1, so nested association filters are resolved from the current scoped binding rather than always from the root query source.