Cinder.QueryBuilder (Cinder v0.5.0)

View Source

Query building functionality for Cinder table components.

Handles the construction of Ash queries with filters, sorting, and pagination for table data loading.

Summary

Functions

Applies filters to an Ash query based on filter configuration and column definitions.

Applies query options like load and select to an Ash query.

Applies sorting to an Ash query based on sort specifications and column definitions.

Applies standard filters by delegating to the appropriate filter module.

Builds a complete query with filters, sorting, and pagination.

Builds error pagination info for failed queries.

Builds expression sort for relationship fields using dot notation.

Builds pagination info from query results and total count.

Extracts sort information from an Ash query for table UI initialization.

Gets the current sort direction for a given key.

Toggles sort direction for a given key in the sort specification.

Toggles sort direction with special handling for query-extracted sorts.

Types

column()

@type column() :: %{
  field: String.t(),
  filterable: boolean(),
  filter_type: atom(),
  filter_fn: function() | nil,
  sort_fn: function() | nil
}

filter()

@type filter() :: %{type: atom(), value: any(), operator: atom()}

filters()

@type filters() :: %{required(String.t()) => filter()}

query_opts()

@type query_opts() :: keyword()

sort_by()

@type sort_by() :: [{String.t(), :asc | :desc}]

Functions

apply_filters(query, filters, columns)

Applies filters to an Ash query based on filter configuration and column definitions.

apply_query_opts(query, opts)

Applies query options like load and select to an Ash query.

apply_sorting(query, sort_by, columns)

Applies sorting to an Ash query based on sort specifications and column definitions.

apply_standard_filter(query, key, filter_config, column)

Applies standard filters by delegating to the appropriate filter module.

build_and_execute(resource, options)

Builds a complete query with filters, sorting, and pagination.

Parameters

  • resource: The Ash resource to query
  • options: Query building options including:
    • :actor - The current user/actor
    • :filters - Filter map
    • :sort_by - Sort specifications
    • :page_size - Number of records per page
    • :current_page - Current page number
    • :columns - Column definitions
    • :query_opts - Additional Ash query and execution options

Supported Query Options

The :query_opts parameter accepts both query building and execution options:

Query Building Options

Execution Options

These options are passed to both Ash.Query.for_read/3 and Ash.read/2:

  • :timeout - Query timeout in milliseconds or :infinity (e.g., :timer.seconds(30))
  • :authorize? - Whether to run authorization during query execution
  • :max_concurrency - Maximum number of processes for parallel loading

Usage Examples

# Simple timeout for long-running queries
query_opts: [timeout: :timer.seconds(30)]

# Query building options
query_opts: [select: [:name, :email], load: [:posts]]

# Combined query building and execution options
query_opts: [
  timeout: :timer.seconds(20),
  authorize?: false,
  select: [:title, :content],
  load: [:author, :comments]
]

Returns

A tuple {:ok, {results, page_info}} or {:error, reason}

build_error_page_info()

Builds error pagination info for failed queries.

build_expression_sort(key)

Builds expression sort for relationship fields using dot notation.

build_page_info_with_total_count(results, current_page, page_size, total_count)

Builds pagination info from query results and total count.

extract_query_sorts(query, columns \\ [])

Extracts sort information from an Ash query for table UI initialization.

Takes an Ash query and returns sort information in the format expected by the table component: [{field_name, direction}]

Parameters

  • query - An Ash.Query struct or resource module
  • columns - Column definitions to map query sorts to table fields

Returns

A list of {field_name, direction} tuples where:

  • field_name is a string matching table column field names
  • direction is :asc or :desc

Examples

# Query with sorts
query = User |> Ash.Query.for_read(:read) |> Ash.Query.sort([{:name, :desc}, {:created_at, :asc}])
extract_query_sorts(query, columns)
# => [{"name", :desc}, {"created_at", :asc}]

# Resource module (no sorts)
extract_query_sorts(User, columns)
# => []

get_sort_direction(sort_by, key)

Gets the current sort direction for a given key.

toggle_sort_direction(current_sort, key)

Toggles sort direction for a given key in the sort specification.

Provides a predictable three-step cycle:

  • none → ascending → descending → none

When starting with extracted query sorts, use toggle_sort_from_query/2 for better UX that handles the transition from query state to user control.

toggle_sort_from_query(current_sort, key)

Toggles sort direction with special handling for query-extracted sorts.

When a column has a sort from query extraction, the first user click provides intuitive behavior:

  • desc (from query) → asc (user takes control)
  • asc (from query) → desc (user takes control) Then follows normal toggle cycle.

This provides better UX when tables start with pre-sorted queries.