Selecto.Expr (Selecto v0.4.5)

Copy Markdown

Ergonomic constructors for Selecto filter and selector AST.

This module returns the tuple and list shapes that Selecto already accepts, making dynamic query composition easier without introducing a new execution path.

Summary

Types

A helper expression that normalizes into Selecto's existing AST.

Functions

Builds an AND filter group.

Appends a filter when a normalized filter is present.

Appends a group-by expression when present.

Appends an order-by expression when present.

Appends a selector when a normalized selector is present.

Builds an array contained-by filter.

Builds an array contains filter.

Builds an array equality filter.

Builds an array overlap filter.

Adds an alias to any selector expression.

Builds an ascending order spec.

Builds an ascending order spec with nulls first.

Builds an ascending order spec with nulls last.

Builds an AVG(...) selector.

Builds a BETWEEN filter.

Builds a shared boolean/operator text search filter.

Builds a CASE expression using {filter, result} pairs.

Builds a COALESCE(...) selector.

Drops nil/empty fragments and wraps the remainder in an AND group.

Drops nil/empty fragments and wraps the remainder in an OR group.

Builds a CONCAT(...) selector.

Builds a contains filter using Selecto's existing :contains operator.

Builds COUNT(*) or COUNT(field) selectors.

Builds COUNT(DISTINCT ...) selectors.

Builds a descending order spec.

Builds a descending order spec with nulls first.

Builds a descending order spec with nulls last.

Builds a suffix LIKE filter.

Builds an equality filter.

Builds an EXISTS (...) filter.

Wraps a field reference or selector expression.

Builds a field-path existence filter for JSONB paths or non-null fields.

Builds a frame tuple for window expressions.

Builds a generic function selector.

Builds a GREATEST(...) selector.

Builds a composite grouping element for use inside ROLLUP(...).

Builds a greater-than filter.

Builds a greater-than-or-equal filter.

Builds an ILIKE filter.

Builds an IN (...) filter.

Builds an IS NULL filter.

Builds a JSON aggregate tuple for Selecto.json_select/2.

Builds a JSON contains filter for Selecto.json_filter/2.

Builds a JSON path-exists filter for Selecto.json_filter/2.

Builds a LEAST(...) selector.

Builds a LIKE filter.

Wraps a literal selector value.

Builds a less-than filter.

Builds a less-than-or-equal filter.

Builds a MySQL-oriented full-text search filter that maps onto :text_search.

Builds a MAX(...) selector.

Conditionally appends a group-by expression when the value is present.

Conditionally appends an order-by expression when the value is present.

Compacts a list of filters with AND semantics and appends it to the query.

Builds a MIN(...) selector.

Builds a not-equal filter.

Normalizes helper-friendly expression forms into Selecto AST.

Builds a negated filter.

Builds a NOT IN (...) filter.

Builds an IS NOT NULL filter.

Builds a NULLIF(...) selector.

Builds an OR filter group.

Builds a shared phrase-intent text search filter.

Conditionally applies a query pipeline function.

Builds a shared plain-token text search filter.

Builds a GROUP BY ROLLUP(...) keyword spec.

Builds a prefix LIKE filter.

Builds a STDDEV(...) selector.

Builds a field IN (subquery) filter.

Builds a SUM(...) selector.

Builds a full-text search filter using Selecto's :text_search operator.

Builds a registered UDF selector or predicate expression.

Builds a VARIANCE(...) selector.

Builds a shared web-style text search filter.

Builds an expression only when the value is present.

Builds a window-function selector for Selecto.select/2.

Types

expr()

@type expr() :: term()

A helper expression that normalizes into Selecto's existing AST.

Functions

and(filters)

Builds an AND filter group.

append_filter(selecto, filter)

@spec append_filter(Selecto.Types.t(), term()) :: Selecto.Types.t()

Appends a filter when a normalized filter is present.

append_group_by(selecto, group_spec)

@spec append_group_by(Selecto.Types.t(), term()) :: Selecto.Types.t()

Appends a group-by expression when present.

append_order_by(selecto, order_spec)

@spec append_order_by(Selecto.Types.t(), term()) :: Selecto.Types.t()

Appends an order-by expression when present.

append_select(selecto, selector)

@spec append_select(Selecto.Types.t(), term()) :: Selecto.Types.t()

Appends a selector when a normalized selector is present.

array_contained(field, values)

@spec array_contained(term(), [term()]) :: tuple()

Builds an array contained-by filter.

array_contains(field, values)

@spec array_contains(term(), [term()]) :: tuple()

Builds an array contains filter.

array_eq(field, values)

@spec array_eq(term(), [term()]) :: tuple()

Builds an array equality filter.

array_overlap(field, values)

@spec array_overlap(term(), [term()]) :: tuple()

Builds an array overlap filter.

as(expression, alias_name)

@spec as(term(), String.t() | atom()) :: tuple()

Adds an alias to any selector expression.

asc(expression)

@spec asc(term()) :: tuple()

Builds an ascending order spec.

asc_nulls_first(expression)

@spec asc_nulls_first(term()) :: tuple()

Builds an ascending order spec with nulls first.

asc_nulls_last(expression)

@spec asc_nulls_last(term()) :: tuple()

Builds an ascending order spec with nulls last.

avg(value)

@spec avg(term()) :: tuple()

Builds an AVG(...) selector.

between(field, min, max)

@spec between(term(), term(), term()) :: tuple()

Builds a BETWEEN filter.

boolean_search(field, value_or_opts, opts \\ [])

@spec boolean_search(term(), term() | keyword(), keyword()) :: tuple()

Builds a shared boolean/operator text search filter.

case_when(pairs, else_clause \\ nil)

@spec case_when([{term(), term()}], term()) :: tuple()

Builds a CASE expression using {filter, result} pairs.

coalesce(values)

@spec coalesce([term()]) :: tuple()

Builds a COALESCE(...) selector.

compact_and(filters)

@spec compact_and([term()]) :: term() | nil

Drops nil/empty fragments and wraps the remainder in an AND group.

compact_or(filters)

@spec compact_or([term()]) :: term() | nil

Drops nil/empty fragments and wraps the remainder in an OR group.

concat(values)

@spec concat([term()]) :: tuple()

Builds a CONCAT(...) selector.

contains(field, value)

@spec contains(term(), term()) :: tuple()

Builds a contains filter using Selecto's existing :contains operator.

count(value \\ "*")

@spec count(term()) :: tuple()

Builds COUNT(*) or COUNT(field) selectors.

count_distinct(value)

@spec count_distinct(term()) :: tuple()

Builds COUNT(DISTINCT ...) selectors.

desc(expression)

@spec desc(term()) :: tuple()

Builds a descending order spec.

desc_nulls_first(expression)

@spec desc_nulls_first(term()) :: tuple()

Builds a descending order spec with nulls first.

desc_nulls_last(expression)

@spec desc_nulls_last(term()) :: tuple()

Builds a descending order spec with nulls last.

ends_with(field, value)

@spec ends_with(term(), String.t()) :: tuple()

Builds a suffix LIKE filter.

eq(field, value)

@spec eq(term(), term()) :: tuple()

Builds an equality filter.

exists(query, params \\ [])

@spec exists(term(), [term()]) :: tuple()

Builds an EXISTS (...) filter.

field(selector)

@spec field(term()) :: tuple()

Wraps a field reference or selector expression.

field_exists(field)

@spec field_exists(term()) :: tuple()

Builds a field-path existence filter for JSONB paths or non-null fields.

frame(type, start_bound, end_bound)

@spec frame(:rows | :range, term(), term()) :: tuple()

Builds a frame tuple for window expressions.

func(function_name, args \\ [])

@spec func(String.t(), term()) :: tuple()

Builds a generic function selector.

greatest(values, maybe_second \\ nil)

@spec greatest([term()] | term(), term() | nil) :: tuple()

Builds a GREATEST(...) selector.

grouping_set(groups)

@spec grouping_set(term()) :: tuple()

Builds a composite grouping element for use inside ROLLUP(...).

gt(field, value)

@spec gt(term(), term()) :: tuple()

Builds a greater-than filter.

gte(field, value)

@spec gte(term(), term()) :: tuple()

Builds a greater-than-or-equal filter.

ilike(field, value)

@spec ilike(term(), term()) :: tuple()

Builds an ILIKE filter.

field in values

Builds an IN (...) filter.

is_null(field)

@spec is_null(term()) :: tuple()

Builds an IS NULL filter.

json_agg(field, opts \\ [])

Builds a JSON aggregate tuple for Selecto.json_select/2.

json_contains(column, value)

@spec json_contains(term(), term()) :: tuple()

Builds a JSON contains filter for Selecto.json_filter/2.

json_extract(column, path, opts_or_direction \\ [])

Builds a JSON extract tuple for Selecto.json_select/2 or Selecto.json_order_by/2.

json_extract_text(column, path, opts_or_direction \\ [])

Builds a JSON text extract tuple for Selecto.json_select/2 or Selecto.json_order_by/2.

json_object_agg(key_field, value_field, opts \\ [])

Builds a JSON object aggregate tuple for Selecto.json_select/2.

json_path_exists(column, path)

@spec json_path_exists(term(), term()) :: tuple()

Builds a JSON path-exists filter for Selecto.json_filter/2.

least(values, maybe_second \\ nil)

@spec least([term()] | term(), term() | nil) :: tuple()

Builds a LEAST(...) selector.

like(field, value)

@spec like(term(), term()) :: tuple()

Builds a LIKE filter.

lit(value)

@spec lit(term()) :: tuple()

Wraps a literal selector value.

lt(field, value)

@spec lt(term(), term()) :: tuple()

Builds a less-than filter.

lte(field, value)

@spec lte(term(), term()) :: tuple()

Builds a less-than-or-equal filter.

match_against(field, value_or_opts, opts \\ [])

@spec match_against(term(), term() | keyword(), keyword()) :: tuple()

Builds a MySQL-oriented full-text search filter that maps onto :text_search.

max(value)

@spec max(term()) :: tuple()

Builds a MAX(...) selector.

maybe(value, fun)

@spec maybe(term(), (term() -> term())) :: term() | nil

Alias for when_present/2.

maybe_group_by(selecto, value, fun)

@spec maybe_group_by(Selecto.Types.t(), term(), (term() -> term())) ::
  Selecto.Types.t()

Conditionally appends a group-by expression when the value is present.

maybe_order_by(selecto, value, fun)

@spec maybe_order_by(Selecto.Types.t(), term(), (term() -> term())) ::
  Selecto.Types.t()

Conditionally appends an order-by expression when the value is present.

merge_where(selecto, filters)

@spec merge_where(Selecto.Types.t(), [term()]) :: Selecto.Types.t()

Compacts a list of filters with AND semantics and appends it to the query.

min(value)

@spec min(term()) :: tuple()

Builds a MIN(...) selector.

neq(field, value)

@spec neq(term(), term()) :: tuple()

Builds a not-equal filter.

normalize(expr)

@spec normalize(expr()) :: term()

Normalizes helper-friendly expression forms into Selecto AST.

not filter

Builds a negated filter.

not_in(field, values)

@spec not_in(term(), [term()]) :: tuple()

Builds a NOT IN (...) filter.

not_null(field)

@spec not_null(term()) :: tuple()

Builds an IS NOT NULL filter.

nullif(left, right)

@spec nullif(term(), term()) :: tuple()

Builds a NULLIF(...) selector.

or(filters)

Builds an OR filter group.

phrase_search(field, value_or_opts, opts \\ [])

@spec phrase_search(term(), term() | keyword(), keyword()) :: tuple()

Builds a shared phrase-intent text search filter.

pipe_if(query, condition, fun)

@spec pipe_if(term(), term(), (term() -> term())) :: term()

Conditionally applies a query pipeline function.

plain_search(field, value_or_opts, opts \\ [])

@spec plain_search(term(), term() | keyword(), keyword()) :: tuple()

Builds a shared plain-token text search filter.

rollup(groups)

@spec rollup(term()) :: keyword()

Builds a GROUP BY ROLLUP(...) keyword spec.

starts_with(field, value)

@spec starts_with(term(), String.t()) :: tuple()

Builds a prefix LIKE filter.

stddev(value)

@spec stddev(term()) :: tuple()

Builds a STDDEV(...) selector.

subquery_in(field, query, params \\ [])

@spec subquery_in(term(), term(), [term()]) :: tuple()

Builds a field IN (subquery) filter.

sum(value)

@spec sum(term()) :: tuple()

Builds a SUM(...) selector.

text_search(field, value_or_opts, opts \\ [])

@spec text_search(term(), term() | keyword(), keyword()) :: tuple()

Builds a full-text search filter using Selecto's :text_search operator.

udf(function_id, args \\ [])

@spec udf(String.t() | atom(), term()) :: tuple()

Builds a registered UDF selector or predicate expression.

variance(value)

@spec variance(term()) :: tuple()

Builds a VARIANCE(...) selector.

web_search(field, value_or_opts, opts \\ [])

@spec web_search(term(), term() | keyword(), keyword()) :: tuple()

Builds a shared web-style text search filter.

when_present(value, fun)

@spec when_present(term(), (term() -> term())) :: term() | nil

Builds an expression only when the value is present.

window(function, arguments \\ [], opts \\ [])

@spec window(atom(), term(), keyword()) :: tuple()

Builds a window-function selector for Selecto.select/2.