Aurora.Ctx.QueryBuilder (Aurora.Ctx v0.1.9)

View Source

Provides functions for building and composing Ecto queries with common operations like filtering, sorting, pagination, and preloading associations.

Key Features

  • Flexible filtering: Support for equality, comparison operators, ranges, and dynamic expressions
  • Pagination: Built-in offset/limit pagination with page and per_page parameters
  • Sorting: Multiple sort directions including null handling options
  • Association preloading: Efficient loading of related data
  • Field selection: Control which fields are returned from queries

Supported Filter Operations

  • Equality: {:field, value}
  • Comparisons: :gt, :ge, :lt, :le, :eq
  • Pattern matching: :like, :ilike
  • Range queries: :between
  • Dynamic expressions for complex logic

Examples

# Basic filtering and sorting
query = from(p in Product)
QueryBuilder.options(query,
  where: [status: :active, {:price, :gt, 100}],
  order_by: [desc: :inserted_at],
  preload: [:category]
)

# Pagination with multiple conditions
QueryBuilder.options(query,
  where: [
    status: :active,
    {:price, :between, 50, 200},
    {:name, :ilike, "%phone%"}
  ],
  paginate: %{page: 2, per_page: 10},
  select: [:id, :name, :price]
)

# Using dynamic expressions
dynamic_filter = dynamic([p], p.category_id in ^category_ids)
QueryBuilder.options(query,
  where: ^dynamic_filter,
  select: [:id, :name, :price]
)

Summary

Functions

options(query, options \\ [])

Applies query options to an Ecto query.

Functions

options(query, options \\ [])

@spec options(
  Ecto.Query.t() | nil,
  keyword()
) :: Ecto.Query.t() | nil

Applies query options to an Ecto query.

Parameters

  • query (Ecto.Query.t() | nil) - Base query to modify

  • options (keyword()) - Options to apply (see below)

Options

Filtering

  • :where - Conditions to filter by (AND logic):

    • Simple equality: {:field, value}
    • Comparison operators:
      • :greater_than, :gt - Greater than
      • :greater_equal_than, :ge - Greater than or equal
      • :less_than, :lt - Less than
      • :less_equal_than, :le - Less than or equal
      • :equal_to, :eq - Equal to
      • :like - Pattern matching with % (any chars) and _ (single char)
      • :ilike - Case-insensitive pattern matching
    • Range operator:
      • :between - Value should be within a start/end range
    • Dynamic queries:
      • dynamic(bindings, query_expression) - Can be used to build complex queries

  • :or_where - Same as :where but with OR logic

Sorting

  • :order_by - Sorting specification:
    • Single field: :name
    • Direction: {:desc, :inserted_at}
    • Multiple: [asc: :name, desc: :price]

Pagination

  • :paginate (map()) - Pagination options with keys:
    • :page (integer()) - Page number (1-based)
    • :per_page (integer()) - Items per page

Data Selection

  • :select - Fields to return:

    • Single: :id
    • List: [:id, :name]
    • Dynamic: ^dynamic_expr

  • :preload - Associations to load:

    • Single: :author
    • Nested: [author: [:company]]

Returns

Ecto.Query.t() | nil - Modified query or nil if input was nil